Document asset transformation feature #10471
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Visit the preview URL for this PR (updated for commit 48dde01): https://flutter-docs-prod--pr10471-document-asset-transformers-7yrye4qk.web.app |
andrewkolos
force-pushed
the
document-asset-transformers
branch
from
e80df44
to
88d65d5
Compare
andrewkolos
force-pushed
the
document-asset-transformers
branch
from
ccd1066
to
2432912
Compare
5 tasks
andrewkolos
commented
Apr 30, 2024
Comment on lines
63
to
69
| ### Automatic transformation of asset files at build time | ||
|
|
||
| You can have asset files transformed by dart packages as they are bundled into | ||
| your app. | ||
| To learn how to do this and write your own asset-transforming packages, see | ||
| [Transforming assets at build time][]. | ||
|
|
There was a problem hiding this comment.
I imagine this to be a fairly niche (even if highly useful) feature, so I didn't want to fully explain it on this page but rather give it its own page and link to that. However, this section feels a bit sparse (and too easy to gloss over) to me. If anyone has ideas to improve this, please let me know.
andrewkolos
requested review from
sfshaza2,
domesticmouse,
johnpryan,
khanhnwin,
parlough,
MaryaBelanger and
atsansone
as code owners
andrewkolos
changed the title
Closed
13 tasks
domesticmouse
approved these changes
May 1, 2024
sfshaza2
reviewed
May 1, 2024
Comment on lines
12
to
13
| You can describe which assets should transformed and which package should be | ||
| used transform them in your `pubspec.yaml` file. |
There was a problem hiding this comment.
Suggested change
| You can describe which assets should transformed and which package should be | |
| used transform them in your `pubspec.yaml` file. | |
| List the assets to be transformed, and by which package, | |
| in your `pubspec.yaml` file. | |
| For example, the following example configures Flutter build | |
| to transform an SVG file to an optimized binary file | |
| with the [`vector_graphics_compiler`][] package on pub.dev: | |
| [`vector_]: {{site.pub-pkg}}/vector_graphics_compiler |
Comment on lines
23
to
26
| With this configuration, `assets/logo.svg` will be transformed by the | ||
| `vector_graphics_compiler` package as it is copied to the build output. This | ||
| package precompiles SVG files into an optimized binary files that can be | ||
| displayed using the `vector_graphics` package, like so: |
There was a problem hiding this comment.
Suggested change
| With this configuration, `assets/logo.svg` will be transformed by the | |
| `vector_graphics_compiler` package as it is copied to the build output. This | |
| package precompiles SVG files into an optimized binary files that can be | |
| displayed using the `vector_graphics` package, like so: | |
| With this configuration, `assets/logo.svg` will be transformed by the | |
| `vector_graphics_compiler` package as it's copied to the build output. | |
| You don't have to write the following code, but it shows what happens | |
| on your behalf, once configured: |
There was a problem hiding this comment.
See #10471 (comment)
| package precompiles SVG files into an optimized binary files that can be | ||
| displayed using the `vector_graphics` package, like so: | ||
|
|
||
| <?code-excerpt "ui/assets_and_images/lib/logo.dart (TransformedAsset)"?> |
There was a problem hiding this comment.
Question: This Dart code is autogenerated, yes? This is just informational, right?
There was a problem hiding this comment.
No, this feature does not generate any application code, it only transforms the asset file. Basically, instead of just copying the asset file the app bundle as-is, it runs dart run vector_graphics_compiler --input="assets/logo.svg" --output=<path to assets dir in build output>.
There was a problem hiding this comment.
Corrected a typo in my previous comment
Comment on lines
39
to
40
| You can specify a string of arguments to passed to an asset transformer, just like | ||
| a command-line program: |
There was a problem hiding this comment.
Suggested change
| You can specify a string of arguments to passed to an asset transformer, just like | |
| a command-line program: | |
| To pass a string of arguments to an asset transformer, | |
| also specify that in the pubspec: |
Comment on lines
51
to
52
| In addition, asset transformers can be chained, with transformations applying in | ||
| the order they are declared. Consider this example using made-up packages: |
There was a problem hiding this comment.
Omigosh, I was wondering that exact thing about now. Excellent!
Suggested change
| In addition, asset transformers can be chained, with transformations applying in | |
| the order they are declared. Consider this example using made-up packages: | |
| Asset transformers can be chained and are applied in | |
| the order they are declared. | |
| Consider the following example using imaginary packages: |
Comment on lines
63
to
64
| Here, `bird.png` is transformed by the `grayscale_filter` package. The output | ||
| is then transformed by `png_optimizer`. |
There was a problem hiding this comment.
Suggested change
| Here, `bird.png` is transformed by the `grayscale_filter` package. The output | |
| is then transformed by `png_optimizer`. | |
| Here, `bird.png` is transformed by the `grayscale_filter` package. | |
| The output is then transformed by `png_optimizer`. |
|
Despite @domesticmouse's approval, please do not land yet. |
|
@andrewkolos, can you ping me directly when you feel this is ready to land? |
|
This should land as part of the Flutter 3.22 release with flutter/samples#2267. |
sfshaza2
reviewed
May 8, 2024
sfshaza2
reviewed
May 8, 2024
Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>
Good idea! Done. |
|
Should this be reverted since 3.22 (and thus this feature) is not released yet? |
|
We're close enough. :)
…On Sun, May 12, 2024 at 1:45 PM Andrew Kolos ***@***.***> wrote:
Should this be reverted since 3.22 (and thus this feature) is not released
yet?
—
Reply to this email directly, view it on GitHub
<#10471 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AKS4PKNONNWXFZJW5E7BSWTZB7IFTAVCNFSM6AAAAABG7LB526VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMBWGM3DSNRRGI>
.
You are receiving this because you modified the open/close state.Message
ID: ***@***.***>
|
ericwindmill
added a commit
to flutter/samples
that referenced
this pull request
May 14, 2024
This adds a sample Flutter project that demonstrates a soon-to-be-released feature, asset transformation[^1]. [PR for flutter.dev documentation](flutter/website#10471). This feature isn't the easiest to explain using documentation, so I think augmenting that documentation with a sample is appropriate. This sample demonstrates 1) how to use an existing Dart package (that is compatible with the feature) as an asset transformer and 2) how to write a Dart package that is compatible with this feature. This should be clear from the README.md. **Advice for reviewing this PR.** The goal here is that most users that read the documentation and follow the link from there to this sample should be able to figure out what the feature does and how to use it. Try to imagine yourself in this position and follow this story. If the feature is still unclear, then there is probably something we can do to improve this sample or the docs. Said more simply, follow these steps: 1) Start at the new section to be added to Flutter.dev (https://flutter-docs-prod--pr10471-document-asset-transformers-cc21qf01.web.app/ui/assets/assets-and-images#automatic-transformation-of-asset-files-at-build-time). It should naturally link you to the sample project. Start with the README and see if things make sense. ## Pre-launch Checklist - [X] I read the [Flutter Style Guide] _recently_, and have followed its advice. - [X] I signed the [CLA]. - [X] I read the [Contributors Guide]. - [X] I updated/added relevant documentation (doc comments with `///`). - [X] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-devrel channel on [Discord]. <!-- Links --> [Flutter Style Guide]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo [CLA]: https://cla.developers.google.com/ [Discord]: https://github.com/flutter/flutter/wiki/Chat [Contributors Guide]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md [^1]: If you are super curious about this feature, see [the tracking issue for its implementation](flutter/flutter#143348). --------- Co-authored-by: Eric Windmill <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Documents the new asset transformation feature (if curious, see flutter/flutter#143348; but the documentation included in this PR should be sufficient for learning about and understanding this feature.)
For reviewers. The documentation includes a link to a yet-to-be-merged sample in the flutter/samples repo. When you arrive at this link, I ask that you review flutter/samples#2267, which is the PR that adds the sample being linked to.
Presubmit checklist