Mar 29, 20184:38 PM - edited Apr 22, 20206:41 AM
HubSpot Employee
Custom Background Image Module/ Banner Image module with text
SOLVE
A Custom Background Image Module
For people who read the old version of this guide: I have found that this post over a year later is still quite popular. Re-reading this post, after learning so much, feels like reading my middle-school diary. As such, I have updated it with the specific audience of ‘people who have not made a module in HubSpot’ in mind. This guide will still go over the same concept, making a custom background image module, but it will be better, like @cbarley’s description below. Here’s the main concept we’re working with, and why we are doing it this way: The module that we make here will look, more or less, the same wherever it is dropped. This means no matching up stylesheets, none of that, and you can customize it all you want. With that in mind, let’s look first at the playing field, so we can understand the components, and then we’ll be able to better use them. To do that, we’ll need to first create the custom module. In Design Tools use the ‘Create a new file’ button or File > Create a new file in [folder] option on the left. It does not matter what you name it, give it a name that means something to you. Here’s what things should look like now, I have labeled a few parts
HTML and HubL This is the section where we’re going to do the majority of our work. In terms of the module, this is essentially what actually gets output on the page.
CSS
This is the section that supports CSS. I believe that currently, HubL is not supported here, so we will only be using CSS that does not require HubL here. CSS that would require HubL would be any CSS call that you would want to customize from the page editor. We don’t need to do that, but it can be nice.
JS This section supports JS, we won’t be using any here, but if we wanted to, we could add it here. This is nice because you don’t need to add anything to your main JS file to support it on each implementation, it will be there wherever the module is present. This can also be a downside: if it conflicts with other JS on the page, so keep that in mind.
Fields This one is pretty important to understand. These are going to be the available fields that you can edit when you are on the page editor. Any text that you want to be able to edit, you need to add a text field for that here.
Now, just adding the field here does not do anything directly, apart from allowing a user to select it and set a value, but that value would not be put anywhere. 1, the HTML and HubL section, is where things actually happen and so we need to put something there that says something akin to ‘when something is set here, that goes there’ We’re going to get deeper into fields as we start to build out the module. Building out the module- HTML First Our module is going to be a full-width background image, that has a main header and a subheader. In building this, I am hoping to convey some general building concepts here as well, so that you the reader will know how to replace parts of it with whatever you want. Don’t want the subheader and instead want a CTA? You should be able to do that by the end of this.
For me, when I am building out a module for the first time, I like to start with the HTML without adding any fields yet. This allows me to get everything in place, and then I can add in the fields after, and then insert their values where I need them. I am going to assume that the reader knows some basic HTML and CSS, or at least enough to Google the things you don’t know that I mention here. The basic build will look something like this:
<div class='banner-image'>
<div class='banner-text-area'>
<h1> My header text </h1>
<h2> My subheader text </h2>
</div>
</div>
Here we have an outer-wrapper div we’re called banner-image, and this is what will display the banner image. Inside that, we have another div called banner-text-area, where we have an h1 and an h2. We’re doing it this way so that the banner image can be full width, while the text will have some styling to put it in the center. We’re now ready to move onto our fields. Adding the fields
At its most basic level, the three things here we will want to be able to change will be the banner image itself, and the header and subheader text. For each of these things we want to change, we need a field. We will use an Image field for the background-image, and two separate text fields for the header and subheader. To add a field, on the right hit ‘Add field’ and then search/find the one you are looking for. Give them a name that will be meaningful to you when you are editing them on the page level. I have gone with Banner Image for my image and Header and Subheader for my text fields. Give yourself a high-five because if you got this far and you’re still saying, “alright, I think I get this” then you are well on your way to doing whatever you want in these modules. Let’s do a quick review of what we have here: In the HTML and HubL area, we have the skeleton of what our module is going to look like On the right, we have 3 Fields that are going to be used in the module. Let’s start with the two text fields because they are the easiest. We know where they are going, right between the h1 and h2. Let's do it Mouse over ‘Header’ first, hit Actions > Copy Value Only
This part is important, we only want to output the value of this field, we don’t want to insert the full snippet, because that’s going to add extra code that we don’t need in this context.
Now, take that value, and add it in between the h1 tags, removing the original text we had. Do the same for Subheader, using Actions > Copy value only, and paste it into where the subheader text was. If you used the same naming conventions as me, your HTML and HubL will now look like this:
Note that if you named your fields something different, they will have a different name here, as long as you used ‘copy value only’ from the field, you’ll have the right code. Now, we want to add in the image. If we use ‘copy value only’ the code will output like this: {{ module.banner_image }} The issue here is that it is going to output the full image HTML, and that won’t work for our purposes. Instead, we’re going to grab just one attribute from it, the src attribute, which stores the URL of the image. We are then going to use that as the value for some inline styling. This is probably one of the more complicated things we’re doing here, but it’s relatively easy. If you followed my naming convention, the code we want to use is: {{ module.banner_image.src }}
That .src at the end says ‘just give me what is in the src attribute of the image’ and we can then use this in our wrapping div like so:
What we’re doing here is we’re saying for this div, have it have a background image that has the value of the image module we’ve added. This allows us to, on the page-level, select an image that we’d like.
Another high-five moment
You’ve made it this far, which means you’re pretty much almost done. The only thing left here is to do some styling tweaks. We have the core structure of everything we need here, we have a field that allows us to select an image, that image is then passed to the div banner-image as its background image. We have two other text fields that will ‘float’ over this. Now, we just need some CSS to make things the right size. With all things CSS, there are many ways to approach this. I am not going to teach CSS here, and I think @cbarley has some fantastic (much better than my) CSS in there, so I am going to steal it and rework it for these purposes. If you copy and paste the following, provided you used my same naming convention, you should be able to publish, pat yourself on the back, and test it out:
Note: We never set any default values for the fields, so when you first preview the module, it will look empty. Select an image and some text, and it should be all set. This is what the final module should look like in the editor: And here’s an example of what it would look like in the preview after selecting an image an adding text:
Now, if you wanted to replace any of the text elements with something else, if you followed the steps here, you would just clone the module, and then add in a new field on the right, have that field output to where you want it to be, and mess around with the styling until you have it as you’d like.
Custom Background Image Module/ Banner Image module with text
SOLVE
Great writeup @mrcruz! We had this convo over Slack, but I'd also like to continue that here/point out another way to set this up for anybody interested.
I like to create background image sections using only a custom module so that it's set up for people that may not be as familiar with code and that the can use moving forward quite easily. The reason being two-fold: one - the background image section can be edited in only one place (the editor) if you do it this way, taking away any confusion for somebody that may not be as familiar with code. and two - so that your code can be modular. With the new CMv2, we can add CSS right in our CSS declarations section, and therefore those styles will carry onto any page it's placed on, regardless of the stylesheet that's attached.
Here's how I'd write it up. In the HTML we'd have:
I like this way because the person who's utilizing the module on the page level won't really have to do anything besides plug in any values they'd want!
Something else that I like to do is put in another single line text field with "no_wrapper=True" setup inline next to the background-image declaration. The declaration would simply be
This way, we can pass in any valid CSS here such as 10% 90%, or center top etc. I find the most common complaint is that background images sometimes cut off parts of the image (as they will if the background-size is set to cover), so at the very least, we can solve on the page level for this with this new field. Especially since not all background images are the same and we wouldn't have to rely on that background-position declaration in the CSS section (we can actually just get rid of that).
Here's what it looks like in the CMv2 editor:
I do like your way of doing this as well, and I think both examples are equally valid, which is a really great thing about HubSpot and how we can edit code in the Design Manager!
Custom Background Image Module/ Banner Image module with text
SOLVE
Great writeup @mrcruz! We had this convo over Slack, but I'd also like to continue that here/point out another way to set this up for anybody interested.
I like to create background image sections using only a custom module so that it's set up for people that may not be as familiar with code and that the can use moving forward quite easily. The reason being two-fold: one - the background image section can be edited in only one place (the editor) if you do it this way, taking away any confusion for somebody that may not be as familiar with code. and two - so that your code can be modular. With the new CMv2, we can add CSS right in our CSS declarations section, and therefore those styles will carry onto any page it's placed on, regardless of the stylesheet that's attached.
Here's how I'd write it up. In the HTML we'd have:
I like this way because the person who's utilizing the module on the page level won't really have to do anything besides plug in any values they'd want!
Something else that I like to do is put in another single line text field with "no_wrapper=True" setup inline next to the background-image declaration. The declaration would simply be
This way, we can pass in any valid CSS here such as 10% 90%, or center top etc. I find the most common complaint is that background images sometimes cut off parts of the image (as they will if the background-size is set to cover), so at the very least, we can solve on the page level for this with this new field. Especially since not all background images are the same and we wouldn't have to rely on that background-position declaration in the CSS section (we can actually just get rid of that).
Here's what it looks like in the CMv2 editor:
I do like your way of doing this as well, and I think both examples are equally valid, which is a really great thing about HubSpot and how we can edit code in the Design Manager!
Custom Background Image Module/ Banner Image module with text
SOLVE
Hi @co_space , you still need to be referencing the module. So for example, it should be {{ module.custom_background_image }}. If you still don't get it to work after that, feel free to DM me!
Custom Background Image Module/ Banner Image module with text
SOLVE
I found that a combination of the two was helpful.. the 50% 50% gave me the desired results...
One thing that I thought would work, but didn't, was to put the height at 100% as well as the width... I want to be able to guarantee the full image is displayed regardless of the resolution of the screen (for a very specific request from a client)
Custom Background Image Module/ Banner Image module with text
SOLVE
hey @paulamc thanks for reaching out. This would work in some email clients but not others. With email, it all comes down to what CSS they support. This page from Campaign Monitor will show you the breakdown per email client. You can try using background-image instead of background which does offer slightly wider support, but still not supported by many major email clients (Outlook 2016 for instance)