Hello AssetMapper Documentation #18370

weaverryan · 2023-06-03T21:33:47Z

Hi!

I wrote some docs! This covers all the important things that I can think of right now :). I'd appreciate any reviews.

Post-Merge Symfony.com TODOs:

On https://symfony.com/doc/current/index.html, add an Introduction link under Front-End that links to https://symfony.com/doc/current/frontend.html
Update the Webpack Encore link on that same page to... probably https://symfony.com/doc/current/frontend.html#webpack-encore ?

Thanks!

weaverryan · 2023-06-03T21:35:56Z

frontend.rst

-
+    frontend/asset_mapper/installation
+    frontend/asset_mapper/usage
+    frontend/asset_mapper/*
    frontend/*


The bottom of https://symfony.com/doc/current/frontend.html is currently "wonky". I think the intention was for the the first, :hidden toctree to "load" all of the encore stuff into the toctree... and then this bottom toctree would only load anything "remaining". In practice, it would render everything.

So, I reduced this to just ONE toctree, which is :hidden:. The 2 documents that are outside of encore/* were added manually under the Other Front-End Articles section.

Fun fact, including documents in a toctree entry is no longer relevant with the PHP based parser IIRC

That IS a fun fact, thank you!

weaverryan · 2023-06-03T21:37:59Z

frontend.rst

-create static CSS and JS files in your ``public/`` directory directly and
-include them in your templates.
+Symfony Frontend Tools
+======================


This document is now a bit more important than before. On https://symfony.com/doc/current/index.html, I don't think we link to it at all. After we merge this, we probably should.

"Webpack Encore" is linking to it. We should probably do the same as with Security and call it "Introduction"?

Good idea. I added some TODO to the PR description for post-merge changes to the main documentation page.

weaverryan · 2023-06-04T14:44:29Z

This is ready to go! About the Code Blocks failure - I've added symfony-tools/symfony-application#16 - but it looks like it's using the 5.4 version of the app, and I'm not sure why.

wouterj

Nice. A cool feature just got cool new documentation 😎

wouterj · 2023-06-04T16:28:33Z

frontend.rst

-create static CSS and JS files in your ``public/`` directory directly and
-include them in your templates.
+Symfony Frontend Tools
+======================


"Webpack Encore" is linking to it. We should probably do the same as with Security and call it "Introduction"?

frontend.rst

frontend/asset_mapper.rst

javiereguiluz

Ryan, thanks a lot for this massive contribution. The new docs are fun to read and super easy to follow. Thanks!

frontend/asset_mapper.rst

wolviey · 2023-06-05T09:56:25Z

I really like all the hard work on assetmapper . its really great, just i wonder is there a way to extend functionality of assetmapper like some php handlers ? i didnt see it in documentation, missed out or not a functionality yet ?

Hanmac · 2023-06-05T12:23:39Z

general question about the AssetMapper stuff
if for example i have some sass/scss stuff, but i don't want to use NoteJS and Webcore,
the AssetMapper could still be helpful for me, right?

weaverryan · 2023-06-05T14:28:51Z

Tweaks handled! Thank you for the HUGE review on a big document (and very fast) ❤️

@wolviey: i wonder is there a way to extend functionality of assetmapper like some php handlers

What kind of extending are you imagining? There is an "asset compiler" system where you can parse and modify the contents of any file in asset mapper. It's a bit more advanced, so I didn't document it on this first pass. You can also decorate a "public path resolver" to change the final, public paths of files.

@Hanmac: i have some sass/scss stuff, but i don't want to use NoteJS and Webcore, the AssetMapper could still be helpful for me, right?

Yes :). This is in the new docs. Fortunately, you can download a standalone dart-sass binary to compile your Sass code, which doesn't require Node or Webpack. I think we could make the process of executing this binary even easier, but it's straightforward and (hopefully) well-documented in this new doc.

wolviey · 2023-06-05T16:39:22Z

@wolviey: i wonder is there a way to extend functionality of assetmapper like some php handlers

What kind of extending are you imagining? There is an "asset compiler" system where you can parse and modify the contents of any file in asset mapper. It's a bit more advanced, so I didn't document it on this first pass. You can also decorate a "public path resolver" to change the final, public paths of files.

Thanks for awesome documentation and good work, easy to read and understandable. Thought things like, people can have tools for custom optimizations on css or js for special to their projects, I wondered is't possible to use assetmapper with custom optimization tools at compile time.

weaverryan · 2023-06-05T19:55:10Z

Thanks for awesome documentation and good work, easy to read and understandable. Thought things like, people can have tools for custom optimizations on css or js for special to their projects, I wondered is't possible to use assetmapper with custom optimization tools at compile time.

The answer is probably yes, and it would be by creating an asset compiler (you can see a few in core - one for js files and 2 for CSS files). With these, you could take the source of a file and change it - like minifying it (not, while that’s possible, that’s better left to the server). In practice, I don’t know yet how useful this stuff will be for that purpose… we’ll see what people come up with. And we may need to add even more hook points depending on what people want to do.

wolviey · 2023-06-05T20:32:24Z

Thanks for awesome documentation and good work, easy to read and understandable. Thought things like, people can have tools for custom optimizations on css or js for special to their projects, I wondered is't possible to use assetmapper with custom optimization tools at compile time.

The answer is probably yes, and it would be by creating an asset compiler (you can see a few in core - one for js files and 2 for CSS files). With these, you could take the source of a file and change it - like minifying it (not, while that’s possible, that’s better left to the server). In practice, I don’t know yet how useful this stuff will be for that purpose… we’ll see what people come up with. And we may need to add even more hook points depending on what people want to do.

Thank you so much for showing way of do this. :) At my side, i have my own typescripts and i like to compile them before deploy automatically. normally i do it with script. collecting all typescripts compile them. some optimizations with css (minification removing unused stuff etc) html and js afterwards and publish the latest html css and js files. what assetmapper give duplicate of this work and also in better some places. thats why i thought it can be good idea to merge them (need to check possible or not) . at server every request doing minification even with locks scary for my part when there can be 1000 page request same time. i prefer to do it offline before deployment. And assetmapper really make this things more less config necessary way. i hope there will more hook points :) Assetmapper Itself is great idea honestly.

weaverryan · 2023-06-06T11:08:27Z

I think this is ready to go :)

bendavies · 2023-06-06T13:21:58Z

frontend/asset_mapper.rst

+    {% endblock %}
+
+If you'd rather download the CSS file and include it locally, you can do that.
+For example, you could download it to ``assets/vendor/bootstrap.min.css`` and


is this a manual process or done via a command?

Currently manually - I've clarified the wording to be more clear :)

weaverryan · 2023-06-06T18:13:19Z

FYI - this is still ready to go, but I also added a new section about page-specific JavaScript, per @bendavies question on Slack :)

This PR was squashed before being merged into the 6.3 branch. Discussion ---------- Hello AssetMapper Documentation Hi! I wrote some docs! This covers all the important things that I can think of right now :). I'd appreciate any reviews. ### Post-Merge Symfony.com TODOs: * [ ] On https://symfony.com/doc/current/index.html, add an `Introduction` link under `Front-End` that links to https://symfony.com/doc/current/frontend.html * [ ] Update the `Webpack Encore` link on that same page to... probably https://symfony.com/doc/current/frontend.html#webpack-encore ? Thanks! Commits ------- ef77936 Hello AssetMapper Documentation

Jibbarth · 2023-06-07T18:21:08Z

frontend/asset_mapper.rst

+This will download the package into an ``assets/vendor/`` directory and update
+the ``importmap.php`` file to point to it. You *should* commit this file to
+your repository.


Is the vendor directory should also be committed or should be gitignored ? In that case, is the recipe add the folder to gitignore ?

Hi! You can't actually commit directories to git - only files. But the meaning here is that you "commit the vendor/ directory and all files inside to git". So the assets/vendor/ directory should NOT be ignored :)

seb-jean · 2023-06-09T20:38:36Z

Hi,
What is the reason for closing this PR?

Kocal · 2023-06-09T20:51:54Z

The PR has been merged, but GitHub does not show as is

seb-jean · 2023-06-09T20:55:30Z

Thanks 👍

seb-jean · 2023-06-12T10:53:06Z

How can we manage fonts? Is it different with AssetMapper? Is there a good practice?

weaverryan · 2023-06-13T14:33:45Z

How can we manage fonts? Is it different with AssetMapper? Is there a good practice?

Good question - it's the same as 3rd party CSS:

A) Search on jsdelivr.com for the font you want. from fontsource - e.g. https://www.jsdelivr.com/package/npm/@fontsource/roboto
B) Copy the link tag from this page into base.html.twig (or, if you want to avoid a CDN, manually download this into assets/vendor/ (e.g. assets/vendor/roboto.css), commit that file, then include a link tag with {{ asset('vendor/roboto.css') }}.

It's "simple" but I would love if it were easier - it may be for 6.4.

weaverryan added 2 commits June 2, 2023 15:50

Initial work

9abaee3

finishing docs

4dd3f16

carsonbot added the Status: Needs Review label Jun 3, 2023

weaverryan added 3 commits June 3, 2023 17:37

Changing title

c0c4ad2

Asset Mapper -> AssetMapper

4fe225f

proofing

efa7638

weaverryan commented Jun 3, 2023

View reviewed changes

weaverryan added 3 commits June 4, 2023 10:29

finishing proofread

ad34308

fixes

c6fc372

removing bad toctree entry

fb54a90

wouterj reviewed Jun 4, 2023

View reviewed changes

javiereguiluz approved these changes Jun 5, 2023

View reviewed changes

frontend/asset_mapper.rst Outdated Show resolved Hide resolved

frontend/asset_mapper.rst Outdated Show resolved Hide resolved

frontend/asset_mapper.rst Outdated Show resolved Hide resolved

frontend/asset_mapper.rst Outdated Show resolved Hide resolved

carsonbot added Status: Reviewed and removed Status: Needs Review labels Jun 5, 2023

weaverryan added 2 commits June 5, 2023 10:20

Tweaks thanks to Wouter and Javier

0e95871

rstdoctor

a681986

updating section about vue/react support

385d810

bendavies reviewed Jun 6, 2023

View reviewed changes

Clarify it's manually done right now

bd55e8e

javiereguiluz added this to the 6.3 milestone Jun 6, 2023

javiereguiluz added the front-end label Jun 6, 2023

Adding section about page-specific assets

7a4c391

rst doctor

721b188

weaverryan closed this Jun 7, 2023

Jibbarth reviewed Jun 7, 2023

View reviewed changes

javiereguiluz mentioned this pull request Jun 16, 2023

[Asset] [AssetMapper] New AssetMapper component: Map assets to publicly… #18268

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hello AssetMapper Documentation #18370

Hello AssetMapper Documentation #18370

weaverryan commented Jun 3, 2023 •

edited

Loading

weaverryan Jun 3, 2023

wouterj Jun 4, 2023

weaverryan Jun 5, 2023

weaverryan Jun 3, 2023

wouterj Jun 4, 2023

weaverryan Jun 5, 2023

weaverryan commented Jun 4, 2023

wouterj left a comment

wouterj Jun 4, 2023

javiereguiluz left a comment

wolviey commented Jun 5, 2023

Hanmac commented Jun 5, 2023

weaverryan commented Jun 5, 2023

wolviey commented Jun 5, 2023

weaverryan commented Jun 5, 2023

wolviey commented Jun 5, 2023

weaverryan commented Jun 6, 2023

bendavies Jun 6, 2023

weaverryan Jun 6, 2023

weaverryan commented Jun 6, 2023

Jibbarth Jun 7, 2023

weaverryan Jun 11, 2023

seb-jean commented Jun 9, 2023

Kocal commented Jun 9, 2023

seb-jean commented Jun 9, 2023

seb-jean commented Jun 12, 2023

weaverryan commented Jun 13, 2023

Hello AssetMapper Documentation #18370

Hello AssetMapper Documentation #18370

Conversation

weaverryan commented Jun 3, 2023 • edited Loading

Post-Merge Symfony.com TODOs:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weaverryan commented Jun 4, 2023

wouterj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

javiereguiluz left a comment

Choose a reason for hiding this comment

wolviey commented Jun 5, 2023

Hanmac commented Jun 5, 2023

weaverryan commented Jun 5, 2023

wolviey commented Jun 5, 2023

weaverryan commented Jun 5, 2023

wolviey commented Jun 5, 2023

weaverryan commented Jun 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weaverryan commented Jun 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seb-jean commented Jun 9, 2023

Kocal commented Jun 9, 2023

seb-jean commented Jun 9, 2023

seb-jean commented Jun 12, 2023

weaverryan commented Jun 13, 2023

weaverryan commented Jun 3, 2023 •

edited

Loading