[PP-1] Document the recommended method of creating file URLs to theme assets (e.g. images)

base_path is added in template_prerprocess_page() (core/includes/theme.inc:1328):

  $variables['base_path']         = base_path();
  $variables['front_page']        = \Drupal::url('<front>');
  $variables['language']          = $language_interface;

As mentioned in #2168231: Twig Functions needed in templates these and other useful system-ish variables should be available to all templates via Twig functions or a single system variable array/object (in an effort not to overwhelm the global namespace).

I don't believe there is any reason it's in the page preprocess and not the html preprocess. At this point, I don't see this getting into 8.0.0 as it could be added by contrib. but there's no reason not to add it for 8.1.0

Just noticed #2168231: Twig Functions needed in templates was pushed to 8.1.x as well.

@jpamental, Thanks for moving this issue forward! Yes, this should be rolled against 8.1.x as I don't see it making it into 8.0.x at this point. Also, the testbot will run a patch against whatever version the issue is marked as, which will cause a bunch of other problems (like the patch not applying) between 8.0.x and 8.1.x.

However, I think a better approach would be to create a Twig global for some sort of a system or drupal variable that would hold base_path as well as other system-wide variables such as isFrontPage or activeThemeName (or however we want to rename those old D7 variables). That way any template (system generated or otherwise) would be able to call system.getBasePath() or drupal.isFrontPage(). Because, who knows, you might need the base path in your field__foo-bar.html.twig template because of some random anchor tag you're building.

Kinda thinking out loud here... If we go with that approach, it would be best to post patch to #2168231: Twig Functions needed in templates as this would solve the issues raised there as well.

This looks like a nice thing to have. Though this is not a bug so moving to feature request. It's already scoped out for 8.1.x

Just some nit picks that could be tackled:

1. +++ b/core/includes/theme.inc
   @@ -1209,6 +1209,7 @@ function _template_preprocess_default_variables() {
   +  $variables['base_path']         = base_path();
   

   The space before the = can be removed here.

2. +++ b/core/includes/theme.inc
   @@ -1260,6 +1261,7 @@ function template_preprocess_html(&$variables) {
    
   +
      $site_config = \Drupal::config('system.site');
   

   nit: Extra linebreak doesn't need to be there.

@jpamental whoops sorry don't pull 8.1.x it's pretty useless until some time, just get the latest 8.0.x. (we usually postpone these 8.1.x issues) until that branch is actually released. I'm guessing that is because of syncing branches is a pain.

With stable theme in core we should update its HTML template's docs as well.

We might want to consider this a task as well, and it might not hurt to add a basic test.

The template files were just added this morning, git pull :)

Using base_path is wrong at least 99% of the time. Use file_create_url(), which is available in Twig as file_url().

I tend to agree with @Wim Leers on this, maybe "close won't fix" is a better approach here. @jpamental is there any use-case that we may be overlooking?

Can that be used to point to unmanaged files, specifically files in the theme or theme's subdirectories?

And more specifically in a path agnostic manner so that it's not tied to the location of the theme on the filesystem.

#21: yes. {{ file_url('core/misc/druplicon.png') }} should work just fine. See the docs of file_create_url().

Although relative to the theme itself, that's a different matter altogether. What's a valid use case for that though? CSS and JS should be loaded via asset libraries. CSS files can reference background images and fonts using paths relative to the CSS file. So which use case is not covered by that?

FYI, file_create_url() is an unfortunate name and apparently we should be using that in D7 too;)

re #23 you may want to avoid heavy images in your CSS for performance and have them in your template instead so that it will load with the page and the browser will hold a placeholder for less jumpiness an parallelize the download.

I'd propose something like this:
<img src="{{ file_url(active_theme_path() ~ '/img/big-ass.png') }}">

Another reason why theme://themename/img/big-ass.png would've been nice. #1308152: Add stream wrappers to access .json files in extensions is still moving forward, so perhaps we can get it for 8.1.

No reason to add a new function then. The patch in #1308152: Add stream wrappers to access .json files in extensions is blocked on review. Let's give it the reviews its needs so that that can be fixed? :)

Yeah that should work. Another example use case for theme-relative would be referencing favicon/touch icon etc. from the html.html.twig template, something I see quite often.

Well, file_url is absolute, do we always want this, base_path allows use of directory variable and therefor is relative, I like this better than calling a twig function in the template although #23/#25 are usable examples. I really want the stream wrapper :)

@Jeff Burnz: You make an excellent point, one that I wanted to make as well now that #1494670: References to CSS, JS, and similar files should be root-relative URLs: avoids mixed content warnings & fewer bytes to send landed a few days ago.

Indeed, usually (99% of the time) you actually want the file URL to be relative. And that's why #1494670 also updated the Twig extension's file_url() function:

      new \Twig_SimpleFunction('file_url', function ($uri) {
        return file_url_transform_relative(file_create_url($uri));
      }),

The wrapping in file_url_transform_relative() makes sure you end up with relative file URLs. So, as of #1494670, it's more difficult to do the thing you shouldn't do 99% of the time, and it's easy to do the right thing.

Of course, we still need the stream wrapper. But at least the absolute file URL problem is solved :)

@Wim, thats great news, fantastic.

@jpamental thats right, but when #1494670 lands it will be relative, you can see this in the latest patch (109). Until then you can always work around this by setting something in preprocess, e.g. $variables['theme_path'] = base_path() . $variables['directory']; etc.

Indeed. And note that #1494670: References to CSS, JS, and similar files should be root-relative URLs: avoids mixed content warnings & fewer bytes to send has already landed in 8.1.x, and in the next day or so it will be committed to 8.0.x.

Mh this adds a function call to each executed template. You could save at least some time by putting it into \_template_preprocess_default_variables

@dawehner see comments #18 through #33. The solution I proposed (and which seems to have agreement) is to use {{ file_url('theme://mytheme/img/llama.png') }}. Which means this is actually blocked on #1308152: Add stream wrappers to access .json files in extensions. Once that lands, all this needs to do, is improve documentation.

I updated the issue summary & title to reflect all this.

Well, yeah, the question is whether these are the only usecases they need

As this shows, the active_theme_path() Twig function (added in #2416857: Add an active_theme_path twig function) was a grave mistake.

#1308152: Add stream wrappers to access .json files in extensions still is open so this is probably still postponed.