Integration Guide

How to integrate the Notations library into your application

This guide shows you how to integrate the Notations library into your web or Node.js application.

Web Applications

Using Web Components

The easiest way to add notation rendering to your web app is using the notations-web package:

npm install notations-web notations

Create a notation viewer:

import { NotationBlock } from "notations-web";
import * as N from "notations";

// Define how to create notation viewers
function createViewer(container) {
  return new N.Carnatic.NotationView(container);
}

// Configure the notation block
const config = {
  createViewer: createViewer,
  cssClasses: {
    sourceContainer: "bg-gray-100 p-4",
    outputContainer: "p-4 bg-white"
  }
};

// Find all  tags and render them
document.querySelectorAll("notation").forEach(elem => {
  new NotationBlock(elem, config);
});

Using HTML Tags

Add notation directly in your HTML:

<notation id="example" showSource="true" caption="My Notation">
\cycle("|4|2|2|")
\beatDuration(4)
Sw: S R G M P D N S.
Sh: sa ri ga ma pa dha ni sa
</notation>

Custom Styling

The web components accept CSS classes for customization:

const config = {
  createViewer: createViewer,
  cssClasses: {
    root: "notation-root",
    sourceContainer: "source-section bg-gray-50",
    sourceCaption: "font-bold text-lg",
    sourceCode: "font-mono text-sm",
    outputLabel: "text-gray-600",
    outputContainer: "notation-output"
  }
};

React Integration

Create a React component for notation:

import React, { useEffect, useRef } from 'react';
import * as N from 'notations';

function NotationViewer({ source }) {
  const containerRef = useRef(null);
  const viewRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // Create view on first render
    if (!viewRef.current) {
      viewRef.current = new N.Carnatic.NotationView(
        containerRef.current
      );
    }

    // Parse and render notation
    const [notation, beatLayout, errors] = N.load(source);

    if (errors.length === 0) {
      viewRef.current.renderNotation(notation, beatLayout);
    } else {
      console.error("Notation errors:", errors);
    }
  }, [source]);

  return <div ref={containerRef} className="notation-container" />;
}

export default NotationViewer;

Use it in your components:

function App() {
  const notationSource = `
    \\cycle("|4|2|2|")
    \\beatDuration(4)
    Sw: S R G M P D N S.
    Sh: sa ri ga ma pa dha ni sa
  `;

  return (
    <div>
      <h1>My Composition</h1>
      <NotationViewer source={notationSource} />
    </div>
  );
}

Vue Integration

Create a Vue component:

<template>
  <div ref="container" class="notation-container"></div>
</template>

<script>
import * as N from 'notations';

export default {
  name: 'NotationViewer',
  props: {
    source: {
      type: String,
      required: true
    }
  },
  data() {
    return {
      view: null
    };
  },
  mounted() {
    this.view = new N.Carnatic.NotationView(this.$refs.container);
    this.renderNotation();
  },
  watch: {
    source() {
      this.renderNotation();
    }
  },
  methods: {
    renderNotation() {
      const [notation, beatLayout, errors] = N.load(this.source);

      if (errors.length === 0) {
        this.view.renderNotation(notation, beatLayout);
      } else {
        console.error('Notation errors:', errors);
      }
    }
  }
};
</script>

Node.js Integration

Use the library in Node.js for server-side rendering or processing:

const N = require('notations');

// Parse notation
const source = `
\\cycle("|4|2|2|")
\\beatDuration(4)
Sw: S R G M P D N S.
`;

const [notation, beatLayout, errors] = N.load(source);

if (errors.length === 0) {
  // Process notation data
  console.log('Notation:', notation);
  console.log('Beat Layout:', beatLayout);

  // Access notation structure
  notation.blocks.forEach(block => {
    console.log('Block:', block);
  });
} else {
  console.error('Errors:', errors);
}

Bundler Configuration

Webpack

The library works with Webpack out of the box. If you encounter issues, ensure you have the necessary loaders:

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js']
  }
};

Vite

Vite works seamlessly with the library:

import { defineConfig } from 'vite';

export default defineConfig({
  // No special configuration needed
});

Error Handling

Always handle parsing errors gracefully:

const [notation, beatLayout, errors] = N.load(source);

if (errors.length > 0) {
  // Display errors to user
  const errorMessages = errors.map(e =>
    `Line ${e.line}, Column ${e.column}: ${e.message}`
  ).join('\n');

  console.error('Notation errors:\n', errorMessages);

  // Show error UI to user
  displayErrorUI(errorMessages);
} else {
  // Render notation
  view.setNotation(notation, beatLayout);
}