daviddarnes / link-peek

A Web Component to unfurl regular links into rich previews

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/[email protected]/link-peek.js"
></script>

<!-- 3rd party CDN, not recommended for production use -->
<script
  type="module"
  src="https://esm.sh/@daviddarnes/[email protected]"
></script>

Credit

With thanks to the following people:

• Zach Leatherman for inspiring this Web Component repo template

link-peek's Issues

Allow for multiple templates on a single page

Is your feature request related to a problem? Please describe.
It would be great if more than one template could be used on a single page. Right now if you want to use a custom template all instances of link-peek will use the exact same template with the ID of link-peek-template.

Describe the solution you'd like
Same behaviour as before but you could override the ID that the component looks for when using a custom template. Here's a sudo code example:

<template id="my-custom-template">
  <blockquote data-key="content"></blockquote>
</template>

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

Any instance without the template attribute would either use the default template within the component or, if there is one, the template with an ID of link-peek-template. This would mean there would be no breaking changes to peoples usage of the component.

Allow for global `api` attribute fallback

Is your feature request related to a problem? Please describe.

With the current implementation, a user is required to provide an api attribute on each instance of link-peek. If someone needed to change the api call to be a different endpoint across an entire site, this would be a rather labor intensive process to do a search and replace.

Describe the solution you'd like

Add the ability to have a <meta name="link-peek-api" content="https://example.com/?${link}" /> tag defined in the head to specify a fallback value if no api attribute was specified. This will allow each link-peek instance to still call a separate api if needed, but we can also have a fallback defined globally.

Describe alternatives you've considered

An alternative to this would be a static attribute on the LinkPeek class that could be used in the same way. However, the class is not currently exported, and so this would not be usable in a module based import.