From 8dfbd1d7d95a12e78708cf695735e0da4777485d Mon Sep 17 00:00:00 2001 From: jdwilkin4 Date: Wed, 11 Oct 2023 11:38:28 -0700 Subject: [PATCH 1/7] docs: Add recipe for using getImage() --- src/content/docs/en/guides/images.mdx | 2 + src/content/docs/en/recipes/getImage.mdx | 105 +++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 src/content/docs/en/recipes/getImage.mdx diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx index e617a05415b30..88a0ae7f4e63d 100644 --- a/src/content/docs/en/guides/images.mdx +++ b/src/content/docs/en/guides/images.mdx @@ -467,6 +467,8 @@ import stars from "~/stars/docline.png"; The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/core-concepts/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `` component. +You can find an example on how to create your own custom image component in this [recipe](/en/recipes/getimage/). + `getImage()` takes an options object with the [same properties as the Image component](#properties) (except `alt`). ```astro diff --git a/src/content/docs/en/recipes/getImage.mdx b/src/content/docs/en/recipes/getImage.mdx new file mode 100644 index 0000000000000..25f7d1db6cbca --- /dev/null +++ b/src/content/docs/en/recipes/getImage.mdx @@ -0,0 +1,105 @@ +--- +title: Build a custom Picture Component +description: Learn how to build a custom Picture Component using the getImage function +i18nReady: true +type: recipe +--- + +The `getImage()` function is used for generating images that will be used elsewhere instead of directly in the HTML. In this recipe, you will learn how to create your own `` component using the `getImage()` function. + + +## Prerequisites +- A project with [SSR](/en/guides/server-side-rendering/) (`output: 'server'`) enabled + + +## Recipe + +1. Create a new Astro component and import the `getImage()` function + + ```astro title="src/components/MyCustomPictureComponent.astro" + --- + import { getImage } from "astro:assets"; + --- + + ``` + +2. Destructure the `props` from `Astro.props`. You can also use TypeScript to type the props. + + ```astro title="src/components/MyCustomPictureComponent.astro" + --- + interface Props { + mobileImgUrl: string | ImageMetadata; + desktopImgUrl: string | ImageMetadata; + alt: string; + } + + import type { ImageMetadata } from "astro"; + const { mobileImgUrl, desktopImgUrl, alt } = Astro.props; + import { getImage } from "astro:assets"; + --- + + ``` + +3. Call the `getImage()` function and pass in the properties you want to use into the options object + + ```astro title="src/components/MyCustomPictureComponent.astro" + --- + interface Props { + mobileImgUrl: string | ImageMetadata; + desktopImgUrl: string | ImageMetadata; + alt: string; + } + + import type { ImageMetadata } from "astro"; + const { mobileImgUrl, desktopImgUrl, alt } = Astro.props; + import { getImage } from "astro:assets"; + + const mobileImg = await getImage({ + src: mobileImgUrl, + format: "webp", + width: 200, + }); + + const desktopImg = await getImage({ + src: desktopImgUrl, + format: "webp", + width: 800, + }); + --- + + ``` + +4. Add the `source` and `img` elements inside the `picture` element + + ```astro title="src/components/MyCustomPictureComponent.astro" + --- + interface Props { + mobileImgUrl: string | ImageMetadata; + desktopImgUrl: string | ImageMetadata; + alt: string; + } + + import type { ImageMetadata } from "astro"; + const { mobileImgUrl, desktopImgUrl, alt } = Astro.props; + import { getImage } from "astro:assets"; + + const mobileImg = await getImage({ + src: mobileImgUrl, + format: "webp", + width: 200, + }); + + const desktopImg = await getImage({ + src: desktopImgUrl, + format: "webp", + width: 800, + }); + --- + + + + + {alt} + + + ``` \ No newline at end of file From 6f5d25743a17cad96a6af051b23f66791281b2b0 Mon Sep 17 00:00:00 2001 From: jdwilkin4 Date: Thu, 12 Oct 2023 15:28:16 -0700 Subject: [PATCH 2/7] fix: review comments --- src/content/docs/en/recipes/getImage.mdx | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/src/content/docs/en/recipes/getImage.mdx b/src/content/docs/en/recipes/getImage.mdx index 25f7d1db6cbca..c341a534557e3 100644 --- a/src/content/docs/en/recipes/getImage.mdx +++ b/src/content/docs/en/recipes/getImage.mdx @@ -8,10 +8,6 @@ type: recipe The `getImage()` function is used for generating images that will be used elsewhere instead of directly in the HTML. In this recipe, you will learn how to create your own `` component using the `getImage()` function. -## Prerequisites -- A project with [SSR](/en/guides/server-side-rendering/) (`output: 'server'`) enabled - - ## Recipe 1. Create a new Astro component and import the `getImage()` function @@ -27,15 +23,16 @@ The `getImage()` function is used for generating images that will be used elsewh ```astro title="src/components/MyCustomPictureComponent.astro" --- + import type { ImageMetadata } from "astro"; + import { getImage } from "astro:assets"; + interface Props { mobileImgUrl: string | ImageMetadata; desktopImgUrl: string | ImageMetadata; alt: string; } - import type { ImageMetadata } from "astro"; const { mobileImgUrl, desktopImgUrl, alt } = Astro.props; - import { getImage } from "astro:assets"; --- ``` @@ -44,26 +41,29 @@ The `getImage()` function is used for generating images that will be used elsewh ```astro title="src/components/MyCustomPictureComponent.astro" --- + import type { ImageMetadata } from "astro"; + import { getImage } from "astro:assets"; + interface Props { mobileImgUrl: string | ImageMetadata; desktopImgUrl: string | ImageMetadata; alt: string; } - import type { ImageMetadata } from "astro"; const { mobileImgUrl, desktopImgUrl, alt } = Astro.props; - import { getImage } from "astro:assets"; const mobileImg = await getImage({ src: mobileImgUrl, format: "webp", width: 200, + height: 200, }); const desktopImg = await getImage({ src: desktopImgUrl, format: "webp", width: 800, + height: 200, }); --- @@ -73,26 +73,29 @@ The `getImage()` function is used for generating images that will be used elsewh ```astro title="src/components/MyCustomPictureComponent.astro" --- + import type { ImageMetadata } from "astro"; + import { getImage } from "astro:assets"; + interface Props { mobileImgUrl: string | ImageMetadata; desktopImgUrl: string | ImageMetadata; alt: string; } - import type { ImageMetadata } from "astro"; const { mobileImgUrl, desktopImgUrl, alt } = Astro.props; - import { getImage } from "astro:assets"; const mobileImg = await getImage({ src: mobileImgUrl, format: "webp", width: 200, + height: 200, }); const desktopImg = await getImage({ src: desktopImgUrl, format: "webp", width: 800, + height: 200, }); --- From da1e160ac7d1f9d04433beb3277c8f0e401ebb3e Mon Sep 17 00:00:00 2001 From: jdwilkin4 Date: Tue, 17 Oct 2023 22:42:43 -0700 Subject: [PATCH 3/7] chore: updating intro for custom img recipe --- src/content/docs/en/guides/images.mdx | 3 ++- ...age.mdx => build-custom-img-component.mdx} | 19 +++++++++++-------- 2 files changed, 13 insertions(+), 9 deletions(-) rename src/content/docs/en/recipes/{getImage.mdx => build-custom-img-component.mdx} (64%) diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx index d2b0745ba62ac..d6ad790100ebf 100644 --- a/src/content/docs/en/guides/images.mdx +++ b/src/content/docs/en/guides/images.mdx @@ -6,6 +6,7 @@ i18nReady: true import Since from '~/components/Since.astro'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import Badge from '~/components/Badge.astro'; +import RecipeLinks from "~/components/RecipeLinks.astro"; Astro provides several ways for you to use images on your site, whether they are stored locally inside your project, linked to from an external URL, or managed in a CMS or CDN! @@ -609,7 +610,7 @@ import stars from "~/stars/docline.png"; The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/core-concepts/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `` component. -You can find an example on how to create your own custom image component in this [recipe](/en/recipes/getimage/). +You can find an example on how to create your own custom image component in this `getImage()` takes an options object with the [same properties as the Image component](#properties) (except `alt`). diff --git a/src/content/docs/en/recipes/getImage.mdx b/src/content/docs/en/recipes/build-custom-img-component.mdx similarity index 64% rename from src/content/docs/en/recipes/getImage.mdx rename to src/content/docs/en/recipes/build-custom-img-component.mdx index c341a534557e3..4869b94cdfebe 100644 --- a/src/content/docs/en/recipes/getImage.mdx +++ b/src/content/docs/en/recipes/build-custom-img-component.mdx @@ -1,18 +1,21 @@ --- -title: Build a custom Picture Component -description: Learn how to build a custom Picture Component using the getImage function +title: Build a custom image component +description: Learn how to build a custom image component that supports media queries using the getImage function i18nReady: true type: recipe --- -The `getImage()` function is used for generating images that will be used elsewhere instead of directly in the HTML. In this recipe, you will learn how to create your own `` component using the `getImage()` function. +Astro provides a couple of built in components that you can use to display and optimize your images. The `` component allows you to display responsive images and work with different formats and sizes. The `` componet will optimze your images and allow you to pass in different formats and quality properties. +But there will be times where you will need to have more customizable options for your images that the `` and `` components currently do not support. + +In this recipe, you will learn how use the `getImage()` function to create your own custom image component that supports the use of media queries/art direction. The purpose of the `getImage()` function is to create images for use outside of direct embedding in HTML. ## Recipe 1. Create a new Astro component and import the `getImage()` function - ```astro title="src/components/MyCustomPictureComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" --- import { getImage } from "astro:assets"; --- @@ -21,7 +24,7 @@ The `getImage()` function is used for generating images that will be used elsewh 2. Destructure the `props` from `Astro.props`. You can also use TypeScript to type the props. - ```astro title="src/components/MyCustomPictureComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; @@ -39,7 +42,7 @@ The `getImage()` function is used for generating images that will be used elsewh 3. Call the `getImage()` function and pass in the properties you want to use into the options object - ```astro title="src/components/MyCustomPictureComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; @@ -69,9 +72,9 @@ The `getImage()` function is used for generating images that will be used elsewh ``` -4. Add the `source` and `img` elements inside the `picture` element +4. Add the `source` and `img` elements inside the `picture` element and then set your desired media queries. - ```astro title="src/components/MyCustomPictureComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; From 4235acadba09265def3be3dad8e90917b8c9d23f Mon Sep 17 00:00:00 2001 From: jdwilkin4 Date: Tue, 17 Oct 2023 22:45:36 -0700 Subject: [PATCH 4/7] fix: remove sentence for link to recipe --- src/content/docs/en/guides/images.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx index d6ad790100ebf..85e7a6029ab3f 100644 --- a/src/content/docs/en/guides/images.mdx +++ b/src/content/docs/en/guides/images.mdx @@ -610,7 +610,7 @@ import stars from "~/stars/docline.png"; The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/core-concepts/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `` component. -You can find an example on how to create your own custom image component in this + `getImage()` takes an options object with the [same properties as the Image component](#properties) (except `alt`). From 67bec62400ea836a216f755740e232bf18e37833 Mon Sep 17 00:00:00 2001 From: jdwilkin4 Date: Thu, 19 Oct 2023 23:37:36 -0700 Subject: [PATCH 5/7] chore: applying review comments --- .../en/recipes/build-custom-img-component.mdx | 33 ++++++++++++++----- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/recipes/build-custom-img-component.mdx b/src/content/docs/en/recipes/build-custom-img-component.mdx index 4869b94cdfebe..e77a66150fd91 100644 --- a/src/content/docs/en/recipes/build-custom-img-component.mdx +++ b/src/content/docs/en/recipes/build-custom-img-component.mdx @@ -5,26 +5,26 @@ i18nReady: true type: recipe --- -Astro provides a couple of built in components that you can use to display and optimize your images. The `` component allows you to display responsive images and work with different formats and sizes. The `` componet will optimze your images and allow you to pass in different formats and quality properties. +Astro provides two built-in components that you can use to display and optimize your images. The `` component allows you to display responsive images and work with different formats and sizes. The `` component will optimize your images and allow you to pass in different formats and quality properties. But there will be times where you will need to have more customizable options for your images that the `` and `` components currently do not support. -In this recipe, you will learn how use the `getImage()` function to create your own custom image component that supports the use of media queries/art direction. The purpose of the `getImage()` function is to create images for use outside of direct embedding in HTML. +In this recipe, you will learn how use the [`getImage()` function](/en/guides/images/#generating-images-with-getimage) to create your own custom image component that supports the use of media queries/art direction. ## Recipe 1. Create a new Astro component and import the `getImage()` function - ```astro title="src/components/MyCustomImageComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" --- import { getImage } from "astro:assets"; --- ``` -2. Destructure the `props` from `Astro.props`. You can also use TypeScript to type the props. +2. Your custom component will receive/use three `props` from `Astro.props`. The `mobileImgUrl` and `desktopImgUrl` `props` are used for creating your image at different viewport sizes. The `alt` prop is used for the image's alt text. These props will be passed wherever you render your custom image components. You can also use TypeScript to type the props. - ```astro title="src/components/MyCustomImageComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" ins={11} --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; @@ -40,9 +40,9 @@ In this recipe, you will learn how use the `getImage()` function to create your ``` -3. Call the `getImage()` function and pass in the properties you want to use into the options object +3. Define each of your responsive images by calling the `getImage()` function with your desired properties. - ```astro title="src/components/MyCustomImageComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" ins={13-18, 20-25} --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; @@ -72,9 +72,9 @@ In this recipe, you will learn how use the `getImage()` function to create your ``` -4. Add the `source` and `img` elements inside the `picture` element and then set your desired media queries. +4. Create a `` element that generates `srcset` with your different images based on your desired media queries. - ```astro title="src/components/MyCustomImageComponent.astro" + ```astro title="src/components/MyCustomImageComponent.astro" ins={28-32} --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; @@ -108,4 +108,19 @@ In this recipe, you will learn how use the `getImage()` function to create your {alt} + ``` + +5. Import and use `` in any `.astro` file. Be sure to pass the necessary props for generating two different images at the different viewport sizes: + + ```astro title="src/pages/index.astro" + --- + import MyCustomImageComponent from "../components/MyCustomImageComponent.astro"; + --- + + + ``` \ No newline at end of file From 00280a97b9654ba1dcf278573946ef6335848e43 Mon Sep 17 00:00:00 2001 From: jdwilkin4 Date: Thu, 19 Oct 2023 23:41:18 -0700 Subject: [PATCH 6/7] fix: grammar --- src/content/docs/en/recipes/build-custom-img-component.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/recipes/build-custom-img-component.mdx b/src/content/docs/en/recipes/build-custom-img-component.mdx index e77a66150fd91..a85aca5789ad3 100644 --- a/src/content/docs/en/recipes/build-custom-img-component.mdx +++ b/src/content/docs/en/recipes/build-custom-img-component.mdx @@ -72,7 +72,7 @@ In this recipe, you will learn how use the [`getImage()` function](/en/guides/im ``` -4. Create a `` element that generates `srcset` with your different images based on your desired media queries. +4. Create a `` element that generates a `srcset` with your different images based on your desired media queries. ```astro title="src/components/MyCustomImageComponent.astro" ins={28-32} --- From b3047d79114545b94c2c49a056355f07856f3c98 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 20 Oct 2023 13:52:19 -0300 Subject: [PATCH 7/7] tiny editing tweaksk --- .../docs/en/recipes/build-custom-img-component.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/recipes/build-custom-img-component.mdx b/src/content/docs/en/recipes/build-custom-img-component.mdx index a85aca5789ad3..76975d6d786c0 100644 --- a/src/content/docs/en/recipes/build-custom-img-component.mdx +++ b/src/content/docs/en/recipes/build-custom-img-component.mdx @@ -7,9 +7,9 @@ type: recipe Astro provides two built-in components that you can use to display and optimize your images. The `` component allows you to display responsive images and work with different formats and sizes. The `` component will optimize your images and allow you to pass in different formats and quality properties. -But there will be times where you will need to have more customizable options for your images that the `` and `` components currently do not support. +When you need options that the `` and `` components do not currently support, you can use the `getImage()` function to create a custom component. -In this recipe, you will learn how use the [`getImage()` function](/en/guides/images/#generating-images-with-getimage) to create your own custom image component that supports the use of media queries/art direction. +In this recipe, you will use the [`getImage()` function](/en/guides/images/#generating-images-with-getimage) to create your own custom image component that displays different source images based on media queries. ## Recipe @@ -22,9 +22,9 @@ In this recipe, you will learn how use the [`getImage()` function](/en/guides/im ``` -2. Your custom component will receive/use three `props` from `Astro.props`. The `mobileImgUrl` and `desktopImgUrl` `props` are used for creating your image at different viewport sizes. The `alt` prop is used for the image's alt text. These props will be passed wherever you render your custom image components. You can also use TypeScript to type the props. +2. Create a new component for your custom image. `MyCustomComponent.astro` will receive three `props` from `Astro.props`. The `mobileImgUrl` and `desktopImgUrl` props are used for creating your image at different viewport sizes. The `alt` prop is used for the image's alt text. These props will be passed wherever you render your custom image components. Add the following imports and define the props that you will use in your component. You can also use TypeScript to type the props. - ```astro title="src/components/MyCustomImageComponent.astro" ins={11} + ```astro title="src/components/MyCustomImageComponent.astro" ins={3, 11} --- import type { ImageMetadata } from "astro"; import { getImage } from "astro:assets"; @@ -123,4 +123,4 @@ In this recipe, you will learn how use the [`getImage()` function](/en/guides/im alt="user profile picture" /> - ``` \ No newline at end of file + ```