data-text-mapper

The data-text-mapper contains some utility functions to convert a structured text with link, tag, scope, and image metadata into a combined plain text or html. As well it's made for encode and decode in both directions.

An example use case it was made for is to convert structured data given e.g. in ics event data to simplier google events by encoding the metadata within the description body.

Examples

dataToText()

Converts structured data into plain text format with metadata encoded as hashtags and scope markers.

const data: TextWithData = {
  description: "Lorem Ipsum",
  url: "https://www.domain.com/",
  tags: ["One", "Two", "Three"],
  scopes: ["One", "Two", "Three"],
  image: "https://www.domain.com/image.jpg",
  document: "https://www.domain.com/flyer.pdf",
};

dataToText(data);

returns

Lorem Ipsum

https://www.domain.com/image.jpg

https://www.domain.com/flyer.pdf

https://www.domain.com/

#One #Two #Three @One @Two @Three

Available attributes:

• description (required) - Main text content
• url (optional) - Link to the event or resource
• tags (optional) - Tags prefixed with #
• scopes (optional) - Scope markers prefixed with @
• image (optional) - URL to an image
• document (optional) - URL to a document (e.g., PDF)

textToData()

Transforms plain text back to a structured data object by extracting URLs, hashtags, scope markers, and embedded metadata.

const text = `Lorem Ipsum

https://www.domain.com/image.jpg

https://www.domain.com/flyer.pdf

https://www.domain.com/

#One #Two #Three @One @Two @Three`;

textToData(text);

returns

{
    description: "Lorem Ipsum",
    url: "https://www.domain.com/",
    tags: ["One", "Two", "Three"],
    scopes: ["One", "Two", "Three"],
    image: "https://www.domain.com/image.jpg",
    document: "https://www.domain.com/flyer.pdf"
}

dataToHtml()

Converts structured data into semantic HTML with microformats classes.

const data: TextWithData = {
  description: "Lorem Ipsum",
  url: "https://www.domain.com/",
  tags: ["One", "Two"],
  scopes: ["Three", "Four"],
  image: "https://www.domain.com/image.jpg",
  document: "https://www.domain.com/flyer.pdf",
};

dataToHtml(data);

returns

<p class="p-description">Lorem Ipsum</p>
<img class="p-photo" src="https://www.domain.com/image.jpg" />
<p class="attachment">
  <a class="u-document" href="https://www.domain.com/flyer.pdf"
    >https://www.domain.com/flyer.pdf</a
  >
</p>
<p class="link">
  <a class="u-url" href="https://www.domain.com/">https://www.domain.com/</a>
</p>
<p class="taxonomy">
  <span class="p-category">#One</span> <span class="p-category">#Two</span>
  <span class="p-scope">@Three</span> <span class="p-scope">@Four</span>
</p>

htmlToData()

Transforms HTML with microformats classes back to a structured data object.

const html = `<p class="p-description">Lorem Ipsum</p>
<img class="p-photo" src="https://www.domain.com/image.jpg" />
<p class="attachment"><a class="u-document" href="https://www.domain.com/flyer.pdf">https://www.domain.com/flyer.pdf</a></p>
<p class="link"><a class="u-url" href="https://www.domain.com/">https://www.domain.com/</a></p>
<p class="taxonomy"><span class="p-category">#One</span> <span class="p-category">#Two</span> <span class="p-scope">@Three</span> <span class="p-scope">@Four</span></p>`;

htmlToData(html);

returns

{
    description: "Lorem Ipsum",
    url: "https://www.domain.com/",
    tags: ["One", "Two"],
    scopes: ["Three", "Four"],
    image: "https://www.domain.com/image.jpg",
    document: "https://www.domain.com/flyer.pdf"
}

More details

For more details and edge case description please take a look into the unit tests.

Disclaimer

Not all functions are written that clean as expected. Improvements will we tracked in github issues. Please mention that 'data-text-mapper' is part of the upcoming 'events-api'.