Sage first-timer queries: inserting image assets into templates and issues with page-header.php

Hi guys,

First of all, thanks for all that you do here. I think you’ve created something wonderful, but I’m still trying to find my way around as a newbie.

Let’s make it clear, I’m not a newbie coder, or a WordPress coder. I’m highly technical, very proficient, quick learner, and understand some of what you are trying to achieve here because I’m simultaneously learning Laravel, and I have some Ruby on Rails experience too.

I will probably, eventually, have some wider feedback about how the documentation hinders a first-timer with Sage, but for now I have some more pressing questions/queries.

  1. How should I include images from the assets folder in templates? Best practice for this doesn’t seem to be documented. I did see reference in Discourse to an Assets\asset_path() function. Is this the best way? And can we get that documented somewhere (perhaps it is already and I can’t find it)?

  2. I’m currently working with page-header.php. Basically, all pages, posts and archives in my theme will have a full-width header image that will fall-back to a default if none exists (hence my including images question). I’m struggling because page-header.php is sometimes in a loop (from, say, page.php) and sometimes not in a loop (from, say, index.php or search.php). So I’m having to fill my page-header.php with conditionals like is_page() and it feels pretty messy.

Have you considered re-structuring this slightly? It feels to me like there should be a page-header.php and an archive-header.php to separate in-loop and not-in-loop variations of what goes at the top of the screen.

Thoughts appreciated.



1 Like
  1. <?= get_template_directory_uri(); ?>/dist/images/file.jpg

  2. Titles could definitely use a re-structure!

1 Like

Both of the following result in the same:

<img src="<?=Assets\asset_path('images/logo.png');?>">
<img src="<?=get_stylesheet_directory_uri();?>/dist/images/logo.png">

I tend to use the latter as it’s common to WordPress and doesn’t require a declaration to use the namespace. It also supports the logo being overridden by child themes, should you absolutely need to use child themes.

The former is better if you are likely to need to change the dist folder.


For the header you can create page-header-archive.php and use:

<?php get_template_part('templates/page-header', 'archive');?> 

I’ll often add something else more descriptive to the get template call before the need to create a new template arises. It’s the reason why there is a fallback.


Thanks guys.

So why does asset_path() exist if best-practice seems to be not to use it? Is it used elsewhere?

Also, just wondering if you guys have ever discussed (perhaps on Roots Radio) the decisions you made in base.php? I just had to strip out some stuff from there because I wanted a full-width (Bootstrap: container-fluid) component in a template, and now I’ve got a load of repetition again.

I know this might stop being a problem when you’re using Yeoman to bolt components in, but it felt like the wrapper hindered me here rather then helping me.



P.S. @Foxaii, you’re in Bristol, right? Have you ever considered joining the Bristol WordPress People meetup that happens there? It’s got a mix of dev’s and users, but they’re always keen to get speakers and I’m sure they’d be interested to hear about Roots!

Asset Path

It is used elsewhere. We use Austin’s Asset Builder as a JSON based pipline for assets. The asset_path function either gets the file path from the JSON manifest file or if the key for the file doesn’t exist in the manifest, it provides a fallback to the dist folder.

Because you aren’t putting the images in the JSON manifest, you are just getting the fallback location, which as I mentioned above, will produce the same result as the traditional WordPress methods.

It does mean that the asset_path function is liable to be dropped if we come up with anything better, which is another reason to use the functionality built into WordPress.


This has been discussed quite a bit if you search the forum. You will need to strip out or add some stuff to accommodate full width sections, but you shouldn’t have to repeat yourself much.

More discussion here: Base wrapper with fullwidth elements and sidebar with DRY

Bristol WordPress People

I’ve missed the last few meetups but I have attended a handful of times over the past year. Simon and Henry have asked me to put a talk together but it’s on a very long to-do list at present.

What are you having to repeat a lot? If it’s just a .container class, I wouldn’t say that’s a horrible thing… that’s basically regualr Bootstrap markup and if you’re going full-width, you’re going to have to have a full-width container, generally .container-fluid with some other type of identifier, as you’ll most likely want to give it a specific background color or image. Then to contain the content by default really, you do have to add a .container eventually.

The workaround to this is keeping the .container class where it is and making use of calc() and vw, as Austin shows here: Base wrapper with fullwidth elements and sidebar with DRY

But even then, you’ll still most likely want to have a .container on the inner content.

Also you could add logic to return a .container or .container-fluid class on the base file, based on a page template array. Check out this gist for code.

Thanks guys - I’ve disappeared on holiday for the week, but will review the thread when I get back. Thanks for all your input!