Skip to content

Add a fixedheader ad style #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add a fixedheader ad style #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1266262
Add a fixedheader ad style
davidfischer Feb 20, 2025
555b7a2
Fix linting issue
davidfischer Feb 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions dist/ethicalads.js
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion dist/ethicalads.min.js
View file
Open in desktop

Large diffs are not rendered by default.

Binary file added docs/_static/fixedheader.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
42 changes: 42 additions & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,46 @@ Using our FixedFooter style:
This FixedFooter placement on our homepage


FixedHeader
~~~~~~~~~~~

.. versionadded:: 1.22

The "FixedHeader" style is a static, text-only or text+image placement
at the top of the screen.
Since it's at the top of the screen, it's almost always seen
(resulting in the highest view rate, generating the most revenue).

There's a few notes and strong recommendations when using this ad style:

* This ad is hidden on mobile. It isn't well suited for sites with a lot of mobile users.
* There are a few breakpoint widths on this ad style and corresponding container sizes.
If needed, these are customizable by setting CSS variables (eg. ``--ea-container-lg``) on the placement div.
* In your CSS styles, you want a style like `[data-ea-style="fixedheader"] { height: 50px; }`.
This ensures the space is pre-allocated for the ad slot so the content isn't pushed down when the ad loads.
We set this on the ad client but there can be a flash where the space isn't allocated before the client loads.
* We recommend you set up :ref:`fallback ads <fallback-ads>`.
This ensures something always fills the slot at the top of the screen.
You don't want to have 50px of blank real estate at the top of your page.

Using our FixedHeader style:

.. code:: html

<!-- Place this div just after the open <body> tag (top of the document) -->
<!-- You can also use `data-ea-type="text"` for a text-only ad -->
<!-- Set style="height 50px" to preallocate space for the ad -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<!-- Set style="height 50px" to preallocate space for the ad -->
<!-- Set style="height: 50px" to preallocate space for the ad -->

I think this is right. But we should probably include this in the default example below, right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ya, maybe mention that it should either be here or via CSS.

<div data-ea-publisher="..." data-ea-type="image" data-ea-style="fixedheader"></div>


.. figure:: _static/fixedheader.png
:align: center
:width: 100%

This FixedHeader placement on our homepage



.. _placements:

Ad placement reporting
Expand Down Expand Up @@ -487,6 +527,8 @@ You can fallback to Carbon Ads with a snippet like this:
</script>


.. _fallback-ads:

Showing content when there isn't an ad
--------------------------------------

Expand Down
5 changes: 4 additions & 1 deletion index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import verge from "verge";

import "./styles.scss";

const AD_CLIENT_VERSION = "1.21.0"; // Sent with the ad request
const AD_CLIENT_VERSION = "1.22.0-alpha"; // Sent with the ad request

// For local testing, set this
// const AD_DECISION_URL = "http://ethicaladserver:5000/api/v1/decision/";
Expand Down Expand Up @@ -986,6 +986,9 @@ export class Placement {
});
container.appendChild(hideButton);
}

// FixedHeader: https://ethical-ad-client.readthedocs.io/en/latest/#fixedheader
// No special elements required
}
}

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "ethical-ad-client",
"version": "1.21.0",
"version": "1.22.0-alpha",
"description": "EthicalAds client",
"main": "dist/client.js",
"scripts": {
Expand Down
257 changes: 257 additions & 0 deletions styles.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ $zindex-styles-fixedfooter: 200;

// Breakpoints (used for stickybox/fixedfooter formats)
$breakpoint-ultrawide: 1300px;
$breakpoint-xl: 1200px;
$breakpoint-lg: 992px;
$breakpoint-md: 768px;
$breakpoint-mobile: 576px;

// Colors
Expand Down Expand Up @@ -185,6 +188,33 @@ $color-bg-dark-stickybox: $color-link;
}
}

[data-ea-publisher] {
--ea-container-md: 720px;
--ea-container-lg: 960px;
--ea-container-xl: 1040px;

--ea-image-width: 120px;
--ea-image-width-xs: 44px;

--ea-fixedheader-height: 50px;

// Necessary to reference SCSS colors with CSS properties
// https://sass-lang.com/documentation/breaking-changes/css-vars/
--ea-stylefixed-bgcolor: #{$color-link-dark};
--ea-stylefixed-bgcolor-dark: #{$color-link};

--ea-link-color: #{$color-link};
--ea-link-color-active: #{darken($color-link, 10%)};
--ea-link-color-callout: #{$color-link-callout};
--ea-link-color-callout-active: #{darken($color-link-callout, 10%)};
--ea-link-color-bold: #{$color-link-bold};
--ea-link-color-dark: #{$color-link-dark};
--ea-link-color-dark-active: #{lighten($color-link-dark, 10%)};
--ea-link-color-callout-dark: #{$color-link-callout-dark};
--ea-link-color-callout-dark-active: #{lighten($color-link-callout-dark, 10%)};
--ea-link-color-bold-dark: #{$color-link-bold-dark};
}

[data-ea-publisher].loaded,
[data-ea-type].loaded {
@include theme-raised;
Expand Down Expand Up @@ -411,6 +441,11 @@ $color-bg-dark-stickybox: $color-link;
}
}

.ea-type-image {
// Fixed footer is for text-only ads (for now)
display: none !important;
}

&.dark {
.ea-type-text {
background: $color-bg-dark-stickybox;
Expand All @@ -435,3 +470,225 @@ $color-bg-dark-stickybox: $color-link;
}
}
}

// Fixed Header ad
// -------------------------------------------------------------------------
// https://ethical-ad-client.readthedocs.io/en/latest/#fixedheader
[data-ea-style="fixedheader"] {
height: var(--ea-fixedheader-height);
width: 100%;
max-width: 100%;

background: var(--ea-stylefixed-bgcolor);
border-bottom: 1px solid var(--ea-background-color);

// Hide the fixedheader ad completely below tablet width
@media (max-width: $breakpoint-md) {
display: none !important;
}
}

[data-ea-style="fixedheader"].loaded {
// The outer div containing data-ea-publisher and data-ea-type

// Text-only or text+image
.ea-type-image,
.ea-type-text {
width: var(--ea-container-xl);
margin: 0 auto;
display: flex;

@media (max-width: $breakpoint-lg) {
width: var(--ea-container-md);
}
@media (max-width: $breakpoint-xl) {
width: var(--ea-container-lg);
}

@include theme-flat;

.ea-content {
background-color: inherit;
max-width: 100%;
margin: 0;
padding: 0;
flex: auto; // Expand to fill remaining space
display: flex;

color: var(--ea-link-color);
a {
&:link {
color: var(--ea-link-color);
}
&:visited {
color: var(--ea-link-color);
}
&:hover {
color: var(--ea-link-color-active);
}
&:active {
color: var(--ea-link-color-active);
}
strong,
b {
color: var(--ea-link-color-bold);
}
}
}

.ea-content .ea-text {
margin-top: 0;
padding: 1em;
flex: auto;
text-align: left;
}

.ea-callout {
max-width: 100%;
margin: 0;
padding: 1em;
flex: initial; // Use the initial width of this item - does not expend

color: var(--ea-link-color-callout);
a {
&:link {
color: var(--ea-link-color-callout);
}
&:visited {
color: var(--ea-link-color-callout);
}
&:hover {
color: var(--ea-link-color-callout-active);
}
&:active {
color: var(--ea-link-color-callout-active);
}
strong,
b {
color: var(--ea-link-color-callout);
}
}

// Hide Ads by EthicalAds on mobile
@media (max-width: $breakpoint-mobile) {
display: none;
}
}
}

// Text+image (displayed horizontally)
.ea-type-image {
img {
width: var(--ea-image-width-xs) !important;
height: auto !important;
margin: 0.6em;
}

.ea-domain {
// Doesn't fit with the image
display: none;
}
}

// Text-only
.ea-type-text {
}

&.dark {
background-color: var(--ea-stylefixed-bgcolor-dark);

.ea-content {
color: var(--ea-link-color-dark);
a {
&:link {
color: var(--ea-link-color-dark);
}
&:visited {
color: var(--ea-link-color-dark);
}
&:hover {
color: var(--ea-link-color-dark-active);
}
&:active {
color: var(--ea-link-color-dark-active);
}
strong,
b {
color: var(--ea-link-color-bold-dark);
}
}
}

.ea-callout {
color: var(--ea-link-color-callout-dark);
a {
&:link {
color: var(--ea-link-color-callout-dark);
}
&:visited {
color: var(--ea-link-color-callout-dark);
}
&:hover {
color: var(--ea-link-color-callout-dark-active);
}
&:active {
color: var(--ea-link-color-callout-dark-active);
}
strong,
b {
color: var(--ea-link-color-callout-dark);
}
}
}
}

&.adaptive {
@media (prefers-color-scheme: dark) {
background-color: var(--ea-stylefixed-bgcolor-dark);

.ea-content {
color: var(--ea-link-color-dark);
a {
&:link {
color: var(--ea-link-color-dark);
}
&:visited {
color: var(--ea-link-color-dark);
}
&:hover {
color: var(--ea-link-color-dark-active);
}
&:active {
color: var(--ea-link-color-dark-active);
}
strong,
b {
color: var(--ea-link-color-bold-dark);
}
}
}

.ea-callout {
color: var(--ea-link-color-callout-dark);
a {
&:link {
color: var(--ea-link-color-callout-dark);
}
&:visited {
color: var(--ea-link-color-callout-dark);
}
&:hover {
color: var(--ea-link-color-callout-dark-active);
}
&:active {
color: var(--ea-link-color-callout-dark-active);
}
strong,
b {
color: var(--ea-link-color-callout-dark);
}
}
}
}
}
}