mono-card

v0.1.0

Published

2 months ago

JavaScript SDK for embedding and controlling Mono Card

Downloads

0High
0Medium
0Low

rivertwilight

mono-card card template embed iframe sdk

MonoCard JavaScript SDK

A lightweight JavaScript SDK for embedding and controlling MonoCard templates in your web applications.

Features

🎨 40+ customizable card templates
🔄 Real-time content updates via postMessage API
🌍 Multi-language support (English, Chinese, Japanese)
🎯 TypeScript definitions included
📦 Zero dependencies
🚀 Easy to integrate

Installation

Via NPM

npm install monocard-sdk

Via CDN

<script src="https://unpkg.com/monocard-sdk@latest/monocard-sdk.js"></script>

Quick Start

Using ESM Import (Recommended for React/Modern Projects)

import MonoCard from 'mono-card';

// In a React component
function MyCard() {
  const containerRef = useRef(null);
  const cardRef = useRef(null);

  useEffect(() => {
    if (containerRef.current && !cardRef.current) {
      cardRef.current = new MonoCard({
        root: containerRef.current,
        template: 'modern',
        lang: 'en',
        width: '100%',
        height: '600px',
      });

      // Update card content
      cardRef.current.setTitle('My Awesome Card');
      cardRef.current.setBody('This is the card description');
      cardRef.current.setAuthor('John Doe');
      cardRef.current.setImage('https://example.com/image.jpg');

      // Customize appearance
      cardRef.current.setBackground('gradient');
      cardRef.current.setDropShadow('even');
      cardRef.current.showQRCode(true);
    }

    return () => {
      if (cardRef.current) {
        cardRef.current.destroy();
        cardRef.current = null;
      }
    };
  }, []);

  return <div ref={containerRef} />;
}

Using Script Tag (Browser)

<!DOCTYPE html>
<html>
  <head>
    <title>MonoCard SDK Example</title>
  </head>
  <body>
    <div id="card-container"></div>

    <script src="https://unpkg.com/monocard-sdk@latest/monocard-sdk.js"></script>
    <script>
      // Initialize MonoCard
      const cardEditor = new MonoCard({
        root: document.getElementById("card-container"),
        template: "modern",
        lang: "en",
        width: "100%",
        height: "600px",
      });

      // Update card content
      cardEditor.setTitle("My Awesome Card");
      cardEditor.setBody("This is the card description");
      cardEditor.setAuthor("John Doe");
      cardEditor.setImage("https://example.com/image.jpg");

      // Customize appearance
      cardEditor.setBackground("gradient");
      cardEditor.setDropShadow("even");
      cardEditor.showQRCode(true);
    </script>
  </body>
</html>

Using CommonJS (Node.js)

const MonoCard = require('mono-card');

const cardEditor = new MonoCard({
  root: document.getElementById("card-container"),
  template: "modern",
  lang: "en",
  width: "100%",
  height: "600px",
});

API Reference

Constructor

`new MonoCard(options)`

Creates a new MonoCard instance and embeds an iframe into the specified container.

Parameters:

| Option | Type | Required | Default | Description | | ------------- | ----------- | -------- | ---------------------- | ----------------------------------------------------- | | root | HTMLElement | Yes | - | DOM element to embed the iframe | | template | string | Yes | - | Template ID (e.g., 'apple', 'googlesearch', 'modern') | | lang | string | No | 'en' | Language code ('en', 'zh', 'jp') | | baseUrl | string | No | 'https://mono.cards' | Base URL for iframe | | initialData | object | No | {} | Initial card data | | width | string | No | '100%' | Iframe width | | height | string | No | '600px' | Iframe height |

Example:

const card = new MonoCard({
  root: document.getElementById("container"),
  template: "modern",
  lang: "en",
  initialData: {
    title: "Welcome",
    body: "Initial content",
  },
});

Content Methods

`setTitle(title: string)`

Set the card title.

cardEditor.setTitle("My Card Title");

`setBody(body: string)`

Set the card body content. Supports markdown.

cardEditor.setBody("This is **bold** text");

`setAuthor(author: string)`

Set the card author name.

cardEditor.setAuthor("Jane Smith");

`setImage(url: string)`

Set the card image. Accepts URL or base64 string.

cardEditor.setImage("https://example.com/image.jpg");

`setIcon(url: string)`

Set the card icon. Accepts URL or base64 string.

cardEditor.setIcon("https://example.com/icon.png");

`setQRCode(data: string)`

Set QR code data or URL.

cardEditor.setQRCode("https://mono.cards");

`setSourceUrl(url: string)`

Set the source URL for the card.

cardEditor.setSourceUrl("https://example.com");

Customization Methods

`setBackground(background: string)`

Set the background style.

Options: 'milky', 'dim', 'gradient', 'none'

cardEditor.setBackground("gradient");

`setDropShadow(shadow: string)`

Set the drop shadow style.

Options: 'none', 'even', 'directional'

cardEditor.setDropShadow("even");

`setShadowOverlay(overlay: string)`

Set the shadow overlay effect.

Options: 'tree', 'leafy', 'palm', 'none'

cardEditor.setShadowOverlay("tree");

`setShadowStrength(strength: number)`

Set shadow strength (0-100).

cardEditor.setShadowStrength(75);

`showQRCode(show: boolean)`

Show or hide the QR code.

cardEditor.showQRCode(true);

Template Control

`setTemplate(template: string)`

Switch to a different template dynamically.

cardEditor.setTemplate("googlesearch");

Available Templates:

modern - Modern card design
googlesearch - Google search result style
twitter - Twitter-style card
reddit - Reddit-style card
youtube - YouTube-style card
safari - Safari browser style
photo - Photo card template
text - Simple text card
screenshot - Screenshot style
coffee - Coffee shop receipt
And 30+ more templates...

Batch Updates

`updateCard(data: object)`

Update multiple properties at once for better performance.

cardEditor.updateCard({
  cardData: {
    title: "New Title",
    body: "New body content",
    author: "New Author",
    image: "https://example.com/new-image.jpg",
  },
  customizeData: {
    background: "gradient",
    dropShadow: "even",
    showQRCode: true,
  },
  template: "modern",
});

Utility Methods

`getIframeUrl(): string`

Get the current iframe URL with all parameters.

const url = cardEditor.getIframeUrl();
console.log(url);

`destroy()`

Remove the iframe and cleanup event listeners.

cardEditor.destroy();

Event Callbacks

`onReady`

Called when the iframe is ready to receive updates.

cardEditor.onReady = () => {
  console.log("Card is ready!");
  cardEditor.setTitle("Ready!");
};

`onUpdate`

Called when the iframe confirms a data update.

cardEditor.onUpdate = (data) => {
  console.log("Card updated:", data);
};

TypeScript Support

The SDK includes TypeScript definitions for better development experience.

import MonoCard from "monocard-sdk";

const card = new MonoCard({
  root: document.getElementById("container")!,
  template: "apple",
  lang: "en",
});

card.setTitle("TypeScript Example");

Advanced Examples

Dynamic Content Updates

const card = new MonoCard({
  root: document.getElementById("card"),
  template: "modern",
});

// Simulate real-time updates
setInterval(() => {
  const timestamp = new Date().toLocaleTimeString();
  card.setTitle(`Current Time: ${timestamp}`);
}, 1000);

User Input Integration

<input type="text" id="titleInput" placeholder="Enter title" />
<input type="text" id="bodyInput" placeholder="Enter body" />
<button onclick="updateCard()">Update Card</button>

<div id="card-container"></div>

<script>
  const card = new MonoCard({
    root: document.getElementById("card-container"),
    template: "apple",
  });

  function updateCard() {
    const title = document.getElementById("titleInput").value;
    const body = document.getElementById("bodyInput").value;

    card.updateCard({
      cardData: { title, body },
    });
  }
</script>

Template Switcher

const templates = ["apple", "googlesearch", "modern", "twitter"];
let currentIndex = 0;

const card = new MonoCard({
  root: document.getElementById("card"),
  template: templates[0],
});

function nextTemplate() {
  currentIndex = (currentIndex + 1) % templates.length;
  card.setTemplate(templates[currentIndex]);
}

setInterval(nextTemplate, 5000); // Switch every 5 seconds

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Security Considerations

Content Security Policy: The iframe uses postMessage API for secure cross-origin communication.
Sandbox Attributes: The iframe includes allow-scripts and allow-same-origin sandbox attributes.
Input Validation: Always validate and sanitize user input before passing to the SDK.

Troubleshooting

Card Not Displaying

Ensure the root element exists in the DOM before initializing
Check browser console for errors
Verify the template ID is valid

Updates Not Working

Wait for onReady callback before sending updates
Check that postMessage is not blocked by CSP
Verify the iframe has loaded successfully

CORS Issues

The SDK communicates via postMessage, which works cross-origin
Ensure your Content Security Policy allows iframe embedding

License

MIT

Support

Documentation: https://docs.mono.cards
Issues: https://github.com/rivertwilight/monocard/issues
Website: https://mono.cards

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme