Skip to content

Latest commit

 

History

History
116 lines (83 loc) · 3.92 KB

README.md

File metadata and controls

116 lines (83 loc) · 3.92 KB
Raw

link-peek

A Web Component to unfurl regular links into rich previews.

Demo | Simple demo | Further reading

Examples

General usage example:

<script type="module" src="link-peek.js"></script>

<template id="link-peek-template">
  <figure>
    <figcaption>
      <a data-key="data.title, link"></a>
      <p data-key="data.description"></p>
      <img data-key="data.logo.url" />
      <small data-key="data.publisher"></small>
    </figcaption>
    <img data-key="data.image.url" />
  </figure>
</template>

<link-peek api="https://api.microlink.io/?url=${link}">
  <a href="https://darn.es">David Darnes</a>
</link-peek>

In the above example we're utilising the microlink API to retrieve metadata of the linked page and then using the marked up template to present that data.

Note that there are no defaults set for the API or template being used. link-peek operates agnostically of these APIs for great control and independance. This also means we cannot assume a default built in template

Features

This Web Component allows you to:

  • Use public APIs to return and present metadata on a linked web page
  • Create custom templates for your 'unfurled' link previews using a <template> element and data-key="name" data attributes
  • Use a custom template for specific instances using the template attribute
  • Use any public API to populate your 'unfurled' previews

Installation

You have a few options (choose one of these):

  1. Install via npm: npm install @daviddarnes/link-peek
  2. Download the source manually from GitHub into your project.
  3. Skip this step and use the script directly via a 3rd party CDN (not recommended for production use)

Templating

Templates are created using the <template> element with an ID of link-peek-template. Within the template you can use regular HTML elements and to populate them you use the data-key attribute to name the data point you want it to use. For example if I want to use the data point data.description to render a line of text I would write within my template <p data-key="data.description"></p>.

Here's that same example in context:

<script type="module" src="link-peek.js"></script>

<template id="link-peek-template">
  <p data-key="data.description"></p>
</template>

<link-peek api="https://api.microlink.io/?url=${link}">
  <a href="https://darn.es">David Darnes</a>
</link-peek>

You can also use different templates on the same page by using the template attribute to target <template> elements with a specific id:

<template id="custom-template">
  <a data-key="data.description, data.url"></a>
</template>

<link-peek
  api="https://api.microlink.io/?url=${link}"
  template="custom-template"
>
  <a href="https://darn.es">David Darnes</a>
</link-peek>

Note that for and elements the value won't be applied to it's content if the string being returned starts with http and instead will be applied to the href and src attributes respectively.

Usage

Make sure you include the <script> in your project (choose one of these):

<!-- Host yourself -->
<script type="module" src="link-peek.js"></script>
<!-- 3rd party CDN, not recommended for production use -->
<script
  type="module"
  src="https://www.unpkg.com/@daviddarnes/link-peek@1.1.0/link-peek.js"
></script>
<!-- 3rd party CDN, not recommended for production use -->
<script
  type="module"
  src="https://esm.sh/@daviddarnes/link-peek@1.1.0"
></script>

Credit

With thanks to the following people: