npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@topsort/banners

v0.4.0

Published

A web component for displaying Topsort banner ads.

Downloads

78

Readme

version downloads license GitHub Repo stars

Topsort Banner Ad Web component

Usage

Directly from unpkg.com

<script
  async
  type="module"
  src="https://unpkg.com/@topsort/[email protected]/dist/banners.mjs"
></script>
<script async type="module" src="https://unpkg.com/@topsort/analytics.js"></script>
<script>
  // Set API key for auctions and events
  window.TS = {
    token: "<your topsort api key>",
  };
  // Custom behavior can be configured for each site.
  window.TS_BANNERS = {
    // handle the destination link
    getLink(banner) {
      return `https://example.com/${banner.id}`;
    },
    // handle loading/fetching state
    getLoadingElement() {
      const el = document.createElement("div");
      el.innerText = "Loading...";
      return el;
    },
    // handle errors
    getErrorElement() {
      const el = document.createElement("div");
      el.innerText = "Error loading banner";
      return el;
    },
  };
</script>
<body>
  <topsort-banner width="600" height="400" id="<your slot id>"></topsort-banner>
</body>

Rendering multiple banners with one slot ID

You can render multiple banners using the same slot ID and dimensions by setting up a banner context. This is useful when you want to run an auction with multiple results. To do that you have to pass the attribute context="true" to the topsort-banner and use topsort-banner-slot as children elements.

<topsort-banner context="true" width="600" height="400" id="<your slot id>">
  <topsort-banner-slot rank="1"></topsort-banner-slot>
  <topsort-banner-slot rank="2"></topsort-banner-slot>
  <topsort-banner-slot rank="3"></topsort-banner-slot>
</topsort-banner-context>

Banner Attributes

| Name | Type | Description | | ---------------------- | ---------------- | --------------------------------------------------------------------------- | | width | Number | Banner width | | height | Number | Banner height | | id | String | The slot ID for this banner | | category-id* | Optional String | The category ID of the current page | | category-ids* | Optional String | Comma (,) separated list of category IDs, the item must match all | | category-disjunctions* | Optional String | Comma (,) separated list of category IDs, the item must match any | | search-query | Optional String | The search query of the current page | | location | Optional String | The location for geotargeting | | new-tab | Optional Boolean | Opens the banner's link in a new tab (defaults to false) | | context | Optional Boolean | Uses the element as a context provider to render multiple banners |

* Only one of [category-id, category-ids, category-disjunctions] must be set. If multiple are set, only the first will be considered, in that order.

Banner Slot Attributes

| Name | Type | Description | |------|--------|-----------------------------------------------------------------------------------------------------------------------| | rank | Number | The ranking of the slot. Ranks should be sorted the same as the winning bids. The lower the rank, the higher the bid |

Banner Behaviors

| Function Name | Arg type | Return Type | Description | | ------------------- | --------------------------- | ------------- | -------------------------------------------------------- | | getLink | Banner | string | Generates a URL from a banner response | | getLoadingElement | | HTMLElement | A custom element to be shown when the banner is loading. | | getErrorElement | Error | HTMLElement | A custom element to be shown when the banner errors. | | getNoWinnersElement | | HTMLElement | A custom element to be shown when the auction returns no banner. | | getBannerElement | Banner | HTMLElement | A custom clement to be shown when a banner is loaded. |

Banner Interface

| Name | Type | Description | | --------------- | ------------------------------------------- | ---------------------------------------------------------------------------- | | type | "product" \| "vendor" \| "brand" \| "url" | The type of the winning entity, represented by the banner. | | slotId | string | The ID of the winning entity. If the entity is of type URL, this is the URL. | | resolvedBidId | string | The corresponding auction ID of the winning entity. | | asset | [{ url: string }] | An array of url linking to the assets of the banner. |

Listening to events

The banner component emits an event when the state changes. You can listen to this event to write custom logic. The various states are loading, ready, error, and nowinners.

document.querySelector('#my-slot-id').addEventListener('statechange', (event) => {
  console.log(event.detail); // { status: 'ready', banner: { ... } }
});

Running the example

You can play around with the provided index.html file. To run it, you'll need to install the dependencies and start a local server.

git clone https://github.com/Topsort/banners.js.git
cd banners.js
pnpm install
pnpm run dev

Remember to add window.TS.token and modify the slot-id attribute with your own values that you can find at Topsort.