DOCSEARCHbyAlgolia
Submit Docs

CETEIcean

repository·master·Indexed 41 days ago

https://github.com/teic/ceteicean

A JavaScript library (v1.9.5) that renders unmodified TEI XML documents directly in the browser using Web Components. It converts TEI elements into HTML5 Custom Elements, avoiding the need for XSLT transformations while preserving the TEI data model. It includes features for custom rendering behaviors via addBehaviors, Node.js support via jsdom, and CSS styling for tei-prefixed elements.

Tokens
6.9K
Snippets
28
Records
33
Agent score
52%

What's inside CETEIcean

  1. Getting Started with CETEIcean and TEI Publishing

    master

    CETEIcean is a JavaScript library designed to simplify the publication of Text Encoding Initiative (TEI) XML files on the web. It converts TEI XML into HTML5 content that can be rendered in a web browser.

    Important Note on Local File Access

    By default, CETEIcean loads TEI files from external sources. If you attempt to open your index.html file directly from your local file system (using the file:// protocol), many browsers will block the request due to security restrictions. To view your work, you should use one of the following methods:

    • Run a local web server.
    • Host the files on a web server.
    • Use a text editor with a built-in preview feature (e.g., Visual Studio Code with the Html Preview plugin).
    • Use a programming language like Python to run a simple HTTP server.

  2. How CETEIcean works

    master

    CETEIcean is a JavaScript library that allows unmodified TEI (Text Encoding Initiative) documents to be displayed in a web browser without transforming them to HTML first.

    It uses Web Components standards (specifically Custom Elements) to load TEI files dynamically, rename elements to follow Custom Elements conventions, and register them with the browser. This approach preserves the full structure and information of the TEI data model while allowing you to use standard CSS and JavaScript for styling and interaction. Because it uses Custom Elements, there is no risk of element name collisions (e.g., a TEI <p> will not collide with an HTML <p>).

  3. How CETEIcean works for TEI web publishing

    master
    CETEIcean is a JavaScript library that allows XML-TEI files to be visualized directly in a web browser without requiring a prior XSLT transformation to HTML. It works by dynamically loading the TEI file in the browser and mapping TEI elements to HTML elements (often using Custom Elements), enabling the display of textual phenomena marked in TEI within a standard web environment.

  4. Extend CETEIcean functionality with Behaviors

    master

    Behaviors allow you to define how CETEIcean processes specific TEI elements. You can register behaviors using the c.addBehaviors(behaviors) method on your CETEI instance (usually named c).

    There are two main ways to define a behavior:

    1. String/Array mapping: Map a TEI element to a specific HTML tag or array of tags. For example, mapping lb to ['<br>'] will insert a <br> tag inside the <tei-lb> element.
    2. Function mapping: Provide a JavaScript function that receives the element (e) as an argument. The function should return a new DOM node to replace the original element. This is useful for complex logic, such as calculating heading levels based on nesting depth.

    To override or disable a built-in behavior (like hiding the teiHeader), set its value to null in the behaviors object.

    // Example: Mapping 'lb' to '<br>' and creating dynamic headings
let behaviors = {
  "tei": {
    "head": function(e) {
      // Calculate nesting depth using XPath
      let level = document.evaluate("count(ancestor::tei-div)", e, null, XPathResult.NUMBER_TYPE, null);
      let result = document.createElement("h" + level.numberValue);
      for (let n of e.childNodes) {
        result.appendChild(n.cloneNode());
      }
      return result;
    },
    "lb": ["<br>"],
    "teiHeader": null // Disables the default behavior for teiHeader
  }
};

c.addBehaviors(behaviors);

  5. Style TEI elements using CSS Custom Elements

    master

    CETEIcean transforms TEI elements into HTML Custom Elements by prefixing the element name with tei-. You can use these names as CSS selectors to style your document.

    Examples:

    • Styling a <div> as a block: tei-div { display: block; }
    • Styling a list with a specific type: tei-list[type=simple] { list-style-type: none; }
    • Styling highlighted text: tei-hi[rend=italics] { font-style: italic; }
    • Using pseudo-selectors for line breaks: tei-lb:before { white-space: pre; content: "\A"; }
    tei-div {
  display: block;
}

tei-list[type=simple] {
  list-style-type: none;
}

tei-hi[rend=italics] {
  font-style: italic;
}

  6. Quickstart: Publish a TEI file with CETEIcean

    master

    To publish a TEI (Text Encoding Initiative) XML file on the web, follow these steps:

    1. Set up a directory structure:
      tutorial/
    |-- css/tei.css
    |-- js/CETEI.js
    |-- fpn-washington.xml
    |-- index.html
    2. Create an index.html shell that links to your CSS and the CETEI.js library.
    3. Initialize CETEIcean in a <script> tag to load and transform your XML into HTML Custom Elements.
    4. Serve the files using a web server (e.g., Python, Node.js, or VS Code Live Preview) because browsers often block local file access for security reasons.
    <!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="css/tei.css">
  <script src="js/CETEI.js"></script>
</head>
<body>
  <script>
    let c = new CETEI();
    c.getHTML5('fpn-washington.xml', function(data) {
      document.getElementsByTagName("body")[0].appendChild(data);
    });
  </script>
</body>
</html>

  7. Style TEI elements with CSS

    master

    CETEIcean converts TEI elements into HTML Custom Elements by prefixing the element name with tei-. You can use standard CSS to style these elements.

    Common patterns include:

    • Block elements: Use display: block for elements like tei-div or tei-p.
    • Attributes: Target specific attributes using attribute selectors, e.g., tei-list[type=simple] or tei-hi[rend=italics].
    • Pseudo-elements: Use :before to handle line breaks (tei-lb) by inserting newline characters.

    Example CSS for lists and italics:

    /* Style a simple list */
tei-list[type=simple] {
  list-style-type: none;
}
tei-list[type=simple] > tei-item {
  display: list-item;
}

/* Style highlighted text with italics */
tei-hi[rend=italics] {
  font-style: italic;
}

/* Handle line breaks using CSS pseudo-elements */
tei-lb:before {
  white-space: pre;
  content: "\A";
}

  8. Preview TEI/XML files using a web server

    master

    To view the rendered TEI/XML content in a browser, you should serve the files via a web server rather than opening the HTML file directly.

    If you are using Visual Studio Code, you can use the built-in HTML preview (ctrl+shift+v or cmd+shift+v), though you may need to adjust security settings.

    For other environments, you can use one of the following commands to start a local server in your project directory:

    # Using Python 3
python3 -m http.server

# Using Node.js
npx serve

  9. Display a TEI file in a browser

    master

    To display a TEI file, include the CETEI.js file in your HTML and use the getHTML5 method. This method fetches the XML, transforms it into HTML5 Custom Elements, and returns the resulting DOM nodes via a callback.

    By default, CETEIcean saves and restores scroll position via a URL fragment. To disable this (useful for Server Side Rendering), pass ignoreFragmentId: true in the constructor options.

    // Basic usage
var CETEIcean = new CETEI()
CETEIcean.getHTML5("URL_TO_YOUR_TEI.xml", function(data) {
  document.getElementById("TEI").appendChild(data)
})

// Disabling fragment ID scroll management
new CETEI({
  ignoreFragmentId: true
})

  10. Configure index.html to use CETEIcean

    master

    Your index.html acts as the shell for displaying TEI content. You must link the CSS stylesheet, the CETEI.js library, and include a script to initialize the CETEI object and load your XML file.

    1. Link the CSS in the <head>: <link rel="stylesheet" href="css/tei.css">
    2. Link the CETEIcean library in the <head>: <script src="js/CETEI.js"></script>
    3. Add a script block to load and append the TEI content to the <body>.
    <!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <link rel="stylesheet" href="css/tei.css">
  <script src="js/CETEI.js"></script>
</head>
<body>
  <script>
    let c = new CETEI();
    c.getHTML5('fpn-washington.xml', function(data) {
      document.getElementsByTagName("body")[0].appendChild(data);
    });
  </script>
</body>
</html>

  11. How to serve your TEI files locally

    master

    Since CETEIcean loads TEI files from a source location, viewing an HTML file directly from your file system may fail due to browser security restrictions. Use one of the following methods to run a local web server:

    • Python 3: python3 -m http.server
    • Node.js: npx serve
    • VS Code: Use the Html Preview plugin.
    • GitHub Pages: Upload your files to a repository.
    python3 -m http.server

  12. Set up the CETEIcean project structure

    master

    To use CETEIcean, you must maintain a specific directory structure so that the HTML file can correctly locate the library and styles. Create a root folder (e.g., tutorial_es) with the following layout:

    tutorial_es/
    |-- css/
    |   |-- tei.css
    |-- js/
    |   |-- CETEI.js
    |-- Ruy_Diaz-La_Argentina_Manuscrita.xml
    |-- index.html
    |-- README.md
    tutorial_es/
    |-- css/
    |   |-- tei.css
    |-- js/
    |   |-- CETEI.js
    |-- Ruy_Diaz-La_Argentina_Manuscrita.xml
    |-- README.md