Spaces:
Sleeping
Sleeping
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head> | |
| <meta charset="utf-8"> | |
| <meta name="generator" content="quarto-1.6.40"> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"> | |
| <title>Custom Components – fasthtml</title> | |
| <style> | |
| code{white-space: pre-wrap;} | |
| span.smallcaps{font-variant: small-caps;} | |
| div.columns{display: flex; gap: min(4vw, 1.5em);} | |
| div.column{flex: auto; overflow-x: auto;} | |
| div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} | |
| ul.task-list{list-style: none;} | |
| ul.task-list li input[type="checkbox"] { | |
| width: 0.8em; | |
| margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */ | |
| vertical-align: middle; | |
| } | |
| /* CSS for syntax highlighting */ | |
| pre > code.sourceCode { white-space: pre; position: relative; } | |
| pre > code.sourceCode > span { line-height: 1.25; } | |
| pre > code.sourceCode > span:empty { height: 1.2em; } | |
| .sourceCode { overflow: visible; } | |
| code.sourceCode > span { color: inherit; text-decoration: inherit; } | |
| div.sourceCode { margin: 1em 0; } | |
| pre.sourceCode { margin: 0; } | |
| @media screen { | |
| div.sourceCode { overflow: auto; } | |
| } | |
| @media print { | |
| pre > code.sourceCode { white-space: pre-wrap; } | |
| pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; } | |
| } | |
| pre.numberSource code | |
| { counter-reset: source-line 0; } | |
| pre.numberSource code > span | |
| { position: relative; left: -4em; counter-increment: source-line; } | |
| pre.numberSource code > span > a:first-child::before | |
| { content: counter(source-line); | |
| position: relative; left: -1em; text-align: right; vertical-align: baseline; | |
| border: none; display: inline-block; | |
| -webkit-touch-callout: none; -webkit-user-select: none; | |
| -khtml-user-select: none; -moz-user-select: none; | |
| -ms-user-select: none; user-select: none; | |
| padding: 0 4px; width: 4em; | |
| } | |
| pre.numberSource { margin-left: 3em; padding-left: 4px; } | |
| div.sourceCode | |
| { } | |
| @media screen { | |
| pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } | |
| } | |
| </style> | |
| <script src="../site_libs/quarto-nav/quarto-nav.js"></script> | |
| <script src="../site_libs/quarto-nav/headroom.min.js"></script> | |
| <script src="../site_libs/clipboard/clipboard.min.js"></script> | |
| <script src="../site_libs/quarto-search/autocomplete.umd.js"></script> | |
| <script src="../site_libs/quarto-search/fuse.min.js"></script> | |
| <script src="../site_libs/quarto-search/quarto-search.js"></script> | |
| <meta name="quarto:offset" content="../"> | |
| <link href="../favicon.ico" rel="icon"> | |
| <script src="../site_libs/quarto-html/quarto.js"></script> | |
| <script src="../site_libs/quarto-html/popper.min.js"></script> | |
| <script src="../site_libs/quarto-html/tippy.umd.min.js"></script> | |
| <script src="../site_libs/quarto-html/anchor.min.js"></script> | |
| <link href="../site_libs/quarto-html/tippy.css" rel="stylesheet"> | |
| <link href="../site_libs/quarto-html/quarto-syntax-highlighting-549806ee2085284f45b00abea8c6df48.css" rel="stylesheet" id="quarto-text-highlighting-styles"> | |
| <script src="../site_libs/bootstrap/bootstrap.min.js"></script> | |
| <link href="../site_libs/bootstrap/bootstrap-icons.css" rel="stylesheet"> | |
| <link href="../site_libs/bootstrap/bootstrap-e463c5e664eae906a5c2eb38a07ecc3d.min.css" rel="stylesheet" append-hash="true" id="quarto-bootstrap" data-mode="light"> | |
| <script id="quarto-search-options" type="application/json">{ | |
| "location": "navbar", | |
| "copy-button": false, | |
| "collapse-after": 3, | |
| "panel-placement": "end", | |
| "type": "overlay", | |
| "limit": 50, | |
| "keyboard-shortcut": [ | |
| "f", | |
| "/", | |
| "s" | |
| ], | |
| "show-item-context": false, | |
| "language": { | |
| "search-no-results-text": "No results", | |
| "search-matching-documents-text": "matching documents", | |
| "search-copy-link-title": "Copy link to search", | |
| "search-hide-matches-text": "Hide additional matches", | |
| "search-more-match-text": "more match in this document", | |
| "search-more-matches-text": "more matches in this document", | |
| "search-clear-button-title": "Clear", | |
| "search-text-placeholder": "", | |
| "search-detached-cancel-button-title": "Cancel", | |
| "search-submit-button-title": "Submit", | |
| "search-label": "Search" | |
| } | |
| }</script> | |
| <link rel="stylesheet" href="../styles.css"> | |
| <meta property="og:title" content="Custom Components – fasthtml"> | |
| <meta property="og:description" content="The fastest way to create an HTML app"> | |
| <meta property="og:site_name" content="fasthtml"> | |
| <meta name="twitter:title" content="Custom Components – fasthtml"> | |
| <meta name="twitter:description" content="The fastest way to create an HTML app"> | |
| <meta name="twitter:image" content="https://www.fastht.ml/docs/og-image.png"> | |
| <meta name="twitter:creator" content="@jeremyphoward"> | |
| <meta name="twitter:site" content="@answerdotai"> | |
| <meta name="twitter:card" content="summary_large_image"> | |
| <link rel="canonical" href="https://www.fastht.ml/docs/ref/defining_xt_component.html"> | |
| </head> | |
| <body class="nav-sidebar floating nav-fixed"> | |
| <div id="quarto-search-results"></div> | |
| <header id="quarto-header" class="headroom fixed-top"> | |
| <nav class="navbar navbar-expand-lg " data-bs-theme="dark"> | |
| <div class="navbar-container container-fluid"> | |
| <div class="navbar-brand-container mx-auto"> | |
| <a href="../index.html" class="navbar-brand navbar-brand-logo"> | |
| <img src="../logo.svg" alt="" class="navbar-logo"> | |
| </a> | |
| </div> | |
| <div id="quarto-search" class="" title="Search"></div> | |
| <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" role="menu" aria-expanded="false" aria-label="Toggle navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }"> | |
| <span class="navbar-toggler-icon"></span> | |
| </button> | |
| <div class="collapse navbar-collapse" id="navbarCollapse"> | |
| <ul class="navbar-nav navbar-nav-scroll me-auto"> | |
| <li class="nav-item"> | |
| <a class="nav-link" href="https://fastht.ml"> | |
| <span class="menu-text">Home</span></a> | |
| </li> | |
| <li class="nav-item"> | |
| <a class="nav-link" href="https://fastht.ml/about"> | |
| <span class="menu-text">Learn</span></a> | |
| </li> | |
| </ul> | |
| <ul class="navbar-nav navbar-nav-scroll ms-auto"> | |
| <li class="nav-item compact"> | |
| <a class="nav-link" href="https://github.com/answerdotai/fasthtml"> <i class="bi bi-github" role="img"> | |
| </i> | |
| <span class="menu-text"></span></a> | |
| </li> | |
| <li class="nav-item compact"> | |
| <a class="nav-link" href="https://x.com/answerdotai"> <i class="bi bi-twitter" role="img" aria-label="Fast.ai Twitter"> | |
| </i> | |
| <span class="menu-text"></span></a> | |
| </li> | |
| </ul> | |
| </div> <!-- /navcollapse --> | |
| <div class="quarto-navbar-tools"> | |
| </div> | |
| </div> <!-- /container-fluid --> | |
| </nav> | |
| <nav class="quarto-secondary-nav"> | |
| <div class="container-fluid d-flex"> | |
| <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }"> | |
| <i class="bi bi-layout-text-sidebar-reverse"></i> | |
| </button> | |
| <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../ref/concise_guide.html">Reference</a></li><li class="breadcrumb-item"><a href="../ref/defining_xt_component.html">Custom Components</a></li></ol></nav> | |
| <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }"> | |
| </a> | |
| </div> | |
| </nav> | |
| </header> | |
| <!-- content --> | |
| <div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-article page-navbar"> | |
| <!-- sidebar --> | |
| <nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation floating overflow-auto"> | |
| <div class="sidebar-menu-container"> | |
| <ul class="list-unstyled mt-1"> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../index.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Get Started</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item sidebar-item-section"> | |
| <div class="sidebar-item-container"> | |
| <a href="../tutorials/index.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Tutorials</span></a> | |
| <a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="true" aria-label="Toggle section"> | |
| <i class="bi bi-chevron-right ms-2"></i> | |
| </a> | |
| </div> | |
| <ul id="quarto-sidebar-section-1" class="collapse list-unstyled sidebar-section depth1 show"> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../tutorials/by_example.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">FastHTML By Example</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../tutorials/quickstart_for_web_devs.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Web Devs Quickstart</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../tutorials/e2e.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">JS App Walkthrough</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../tutorials/best_practice.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">FastHTML Best Practices</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../tutorials/jupyter_and_fasthtml.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Using Jupyter to write FastHTML</span></a> | |
| </div> | |
| </li> | |
| </ul> | |
| </li> | |
| <li class="sidebar-item sidebar-item-section"> | |
| <div class="sidebar-item-container"> | |
| <a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true"> | |
| <span class="menu-text">Explanations</span></a> | |
| <a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true" aria-label="Toggle section"> | |
| <i class="bi bi-chevron-right ms-2"></i> | |
| </a> | |
| </div> | |
| <ul id="quarto-sidebar-section-2" class="collapse list-unstyled sidebar-section depth1 show"> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/background_tasks.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Background Tasks</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/explaining_xt_components.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text"><strong>FT</strong> Components</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/faq.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">FAQ</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/minidataapi.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">MiniDataAPI Spec</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/oauth.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">OAuth</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/routes.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Routes</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/stripe.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Stripe</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../explains/websockets.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">WebSockets</span></a> | |
| </div> | |
| </li> | |
| </ul> | |
| </li> | |
| <li class="sidebar-item sidebar-item-section"> | |
| <div class="sidebar-item-container"> | |
| <a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-3" role="navigation" aria-expanded="true"> | |
| <span class="menu-text">Reference</span></a> | |
| <a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-3" role="navigation" aria-expanded="true" aria-label="Toggle section"> | |
| <i class="bi bi-chevron-right ms-2"></i> | |
| </a> | |
| </div> | |
| <ul id="quarto-sidebar-section-3" class="collapse list-unstyled sidebar-section depth1 show"> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../ref/concise_guide.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Concise reference</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../ref/best_practice.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">FastHTML Best Practices</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../ref/defining_xt_component.html" class="sidebar-item-text sidebar-link active"> | |
| <span class="menu-text">Custom Components</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../ref/handlers.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Handling handlers</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../ref/live_reload.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Live Reloading</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../ref/response_types.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Response Types</span></a> | |
| </div> | |
| </li> | |
| </ul> | |
| </li> | |
| <li class="sidebar-item sidebar-item-section"> | |
| <div class="sidebar-item-container"> | |
| <a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-4" role="navigation" aria-expanded="true"> | |
| <span class="menu-text">Source</span></a> | |
| <a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-4" role="navigation" aria-expanded="true" aria-label="Toggle section"> | |
| <i class="bi bi-chevron-right ms-2"></i> | |
| </a> | |
| </div> | |
| <ul id="quarto-sidebar-section-4" class="collapse list-unstyled sidebar-section depth1 show"> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/core.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Core</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/components.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Components</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/xtend.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Component extensions</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/js.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Javascript examples</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/pico.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Pico.css components</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/svg.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">SVG</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/jupyter.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Jupyter compatibility</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/oauth.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">OAuth</span></a> | |
| </div> | |
| </li> | |
| <li class="sidebar-item"> | |
| <div class="sidebar-item-container"> | |
| <a href="../api/cli.html" class="sidebar-item-text sidebar-link"> | |
| <span class="menu-text">Command Line Tools</span></a> | |
| </div> | |
| </li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| </nav> | |
| <div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"></div> | |
| <!-- margin-sidebar --> | |
| <div id="quarto-margin-sidebar" class="sidebar margin-sidebar"> | |
| <nav id="TOC" role="doc-toc" class="toc-active"> | |
| <h2 id="toc-title">On this page</h2> | |
| <ul> | |
| <li><a href="#notstr" id="toc-notstr" class="nav-link active" data-scroll-target="#notstr">NotStr</a></li> | |
| <li><a href="#automatic-creation" id="toc-automatic-creation" class="nav-link" data-scroll-target="#automatic-creation">Automatic Creation</a></li> | |
| <li><a href="#manual-creation" id="toc-manual-creation" class="nav-link" data-scroll-target="#manual-creation">Manual Creation</a> | |
| <ul class="collapse"> | |
| <li><a href="#underscores-in-tags" id="toc-underscores-in-tags" class="nav-link" data-scroll-target="#underscores-in-tags">Underscores in tags</a></li> | |
| <li><a href="#symbols-ie-in-tags" id="toc-symbols-ie-in-tags" class="nav-link" data-scroll-target="#symbols-ie-in-tags">Symbols (ie @) in tags</a></li> | |
| <li><a href="#symbols-ie-in-tag-attributes" id="toc-symbols-ie-in-tag-attributes" class="nav-link" data-scroll-target="#symbols-ie-in-tag-attributes">Symbols (ie @) in tag attributes</a></li> | |
| </ul></li> | |
| </ul> | |
| <div class="toc-actions"><ul><li><a href="https://github.com/AnswerDotAI/fasthtml/issues/new" class="toc-action"><i class="bi bi-github"></i>Report an issue</a></li></ul></div><div class="quarto-alternate-formats"><h2>Other Formats</h2><ul><li><a href="defining_xt_component.md"><i class="bi bi-file-code"></i>CommonMark</a></li></ul></div></nav> | |
| </div> | |
| <!-- main --> | |
| <main class="content" id="quarto-document-content"> | |
| <header id="title-block-header" class="quarto-title-block default"><nav class="quarto-page-breadcrumbs quarto-title-breadcrumbs d-none d-lg-block" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../ref/concise_guide.html">Reference</a></li><li class="breadcrumb-item"><a href="../ref/defining_xt_component.html">Custom Components</a></li></ol></nav> | |
| <div class="quarto-title"> | |
| <h1 class="title">Custom Components</h1> | |
| </div> | |
| <div class="quarto-title-meta"> | |
| </div> | |
| </header> | |
| <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! --> | |
| <p>The majority of the time the default <a href="../explains/explaining_xt_components.html">ft components</a> are all you need (for example <code>Div</code>, <code>P</code>, <code>H1</code>, etc.).</p> | |
| <div class="callout callout-style-default callout-tip callout-titled"> | |
| <div class="callout-header d-flex align-content-center"> | |
| <div class="callout-icon-container"> | |
| <i class="callout-icon"></i> | |
| </div> | |
| <div class="callout-title-container flex-fill"> | |
| Pre-requisite Knowledge | |
| </div> | |
| </div> | |
| <div class="callout-body-container callout-body"> | |
| <p>If you don’t know what an ft component is, you should read <a href="../explains/explaining_xt_components.html">the explaining ft components explainer first</a>.</p> | |
| </div> | |
| </div> | |
| <p>However, there are many situations where you need a custom ft component that creates a unique HTML tag (for example <code><zero-md></zero-md></code>). There are many options in FastHTML to do this, and this section will walk through them. Generally you want to use the highest level option that fits your needs.</p> | |
| <div class="callout callout-style-default callout-tip callout-titled"> | |
| <div class="callout-header d-flex align-content-center"> | |
| <div class="callout-icon-container"> | |
| <i class="callout-icon"></i> | |
| </div> | |
| <div class="callout-title-container flex-fill"> | |
| Real-world example | |
| </div> | |
| </div> | |
| <div class="callout-body-container callout-body"> | |
| <p><a href="https://isaac-flath.github.io/website/posts/boots/FasthtmlTutorial.html">This external tutorial</a> walks through a practical situation where you may want to create a custom HTML tag using a custom ft component. Seeing a real-world example is a good way to understand why the contents of this guide is useful.</p> | |
| </div> | |
| </div> | |
| <section id="notstr" class="level2"> | |
| <h2 class="anchored" data-anchor-id="notstr">NotStr</h2> | |
| <p>The first way is to use the <code>NotStr</code> class to use an HTML tag as a string. It works as a one-off but quickly becomes harder to work with as complexity grows. However we can see that you can genenrate the same xml using <code>NotStr</code> as the out-of-the-box components.</p> | |
| <div id="cell-5" class="cell"> | |
| <div class="sourceCode cell-code" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> fasthtml.common <span class="im">import</span> NotStr,Div, to_xml</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| <div id="cell-6" class="cell"> | |
| <div class="sourceCode cell-code" id="cb2"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>div_NotStr <span class="op">=</span> NotStr(<span class="st">'<div></div>'</span>) </span> | |
| <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="bu">print</span>(div_NotStr)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| <div class="cell-output cell-output-stdout"> | |
| <pre><code><div></div></code></pre> | |
| </div> | |
| </div> | |
| </section> | |
| <section id="automatic-creation" class="level2"> | |
| <h2 class="anchored" data-anchor-id="automatic-creation">Automatic Creation</h2> | |
| <p>The next (and better) approach is to let FastHTML generate the component function for you. As you can see in our <code>assert</code> this creates a function that creates the HTML just as we wanted. This works even though there is not a <code>Some_never_before_used_tag</code> function in the <code>fasthtml.components</code> source code (you can verify this yourself by looking at the source code).</p> | |
| <div class="callout callout-style-default callout-tip callout-titled"> | |
| <div class="callout-header d-flex align-content-center"> | |
| <div class="callout-icon-container"> | |
| <i class="callout-icon"></i> | |
| </div> | |
| <div class="callout-title-container flex-fill"> | |
| Tip | |
| </div> | |
| </div> | |
| <div class="callout-body-container callout-body"> | |
| <p>Typically these tags are needed because a CSS or Javascript library created a new XML tag that isn’t default HTML. For example the <code>zero-md</code> javascript library looks for a <code><zero-md></zero-md></code> tag to know what to run its javascript code on. Most CSS libraries work by creating styling based on the <code>class</code> attribute, but they can also apply styling to an arbitrary HTML tag that they made up.</p> | |
| </div> | |
| </div> | |
| <div id="cell-8" class="cell"> | |
| <div class="sourceCode cell-code" id="cb4"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> fasthtml.components <span class="im">import</span> Some_never_before_used_tag</span> | |
| <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>Some_never_before_used_tag()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| <div class="cell-output cell-output-display cell-output-markdown"> | |
| <div class="sourceCode" id="cb5"><pre class="sourceCode html code-with-copy"><code class="sourceCode html"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="dt"><</span><span class="kw">some-never-before-used-tag</span><span class="dt">></</span><span class="kw">some-never-before-used-tag</span><span class="dt">></span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| </div> | |
| </section> | |
| <section id="manual-creation" class="level2"> | |
| <h2 class="anchored" data-anchor-id="manual-creation">Manual Creation</h2> | |
| <p>The automatic creation isn’t magic. It’s just calling a python function <a href="https://www.fastht.ml/docs/api/components.html#__getattr__"><code>__getattr__</code></a> and you can call it yourself to get the same result.</p> | |
| <div id="cell-11" class="cell"> | |
| <div class="sourceCode cell-code" id="cb6"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="im">import</span> fasthtml</span> | |
| <span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>auto_called <span class="op">=</span> fasthtml.components.Some_never_before_used_tag()</span> | |
| <span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>manual_called <span class="op">=</span> fasthtml.components.<span class="fu">__getattr__</span>(<span class="st">'Some_never_before_used_tag'</span>)()</span> | |
| <span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a><span class="co"># Proving they generate the same xml</span></span> | |
| <span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a><span class="cf">assert</span> to_xml(auto_called) <span class="op">==</span> to_xml(manual_called)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| <p>Knowing that, we know that it’s possible to create a different function that has different behavior than FastHTMLs default behavior by modifying how the <code>___getattr__</code> function creates the components! It’s only a few lines of code and reading that what it does is a great way to understand components more deeply.</p> | |
| <div class="callout callout-style-default callout-tip callout-titled"> | |
| <div class="callout-header d-flex align-content-center"> | |
| <div class="callout-icon-container"> | |
| <i class="callout-icon"></i> | |
| </div> | |
| <div class="callout-title-container flex-fill"> | |
| Tip | |
| </div> | |
| </div> | |
| <div class="callout-body-container callout-body"> | |
| <p>Dunder methods and functions are special functions that have double underscores at the beginning and end of their name. They are called at specific times in python so you can use them to cause customized behavior that makes sense for your specific use case. They can appear magical if you don’t know how python works, but they are extremely commonly used to modify python’s default behavior (<code>__init__</code> is probably the most common one).</p> | |
| <p>In a module <a href="https://www.fastht.ml/docs/api/components.html#__getattr__"><code>__getattr__</code></a> is called to get an attribute. In <code>fasthtml.components</code>, this is defined to create components automatically for you.</p> | |
| </div> | |
| </div> | |
| <p>For example if you want a component that creates <code><path></path></code> that doesn’t conflict names with <a href="https://docs.python.org/3/library/pathlib.html#pathlib.Path"><code>pathlib.Path</code></a> you can do that. FastHTML automatically creates new components with a 1:1 mapping and a consistent name, which is almost always what you want. But in some cases you may want to customize that and you can use the <a href="https://www.fastht.ml/docs/api/components.html#ft_hx"><code>ft_hx</code></a> function to do that differently than the default.</p> | |
| <div id="cell-14" class="cell"> | |
| <div class="sourceCode cell-code" id="cb7"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> fasthtml.common <span class="im">import</span> ft_hx</span> | |
| <span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="kw">def</span> ft_path(<span class="op">*</span>c, target_id<span class="op">=</span><span class="va">None</span>, <span class="op">**</span>kwargs): </span> | |
| <span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> ft_hx(<span class="st">'path'</span>, <span class="op">*</span>c, target_id<span class="op">=</span>target_id, <span class="op">**</span>kwargs)</span> | |
| <span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a>ft_path()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| <div class="cell-output cell-output-display cell-output-markdown"> | |
| <div class="sourceCode" id="cb8"><pre class="sourceCode html code-with-copy"><code class="sourceCode html"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="dt"><</span><span class="kw">path</span><span class="dt">></</span><span class="kw">path</span><span class="dt">></span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| </div> | |
| <p>We can add any behavior in that function that we need to, so let’s go through some progressively complex examples that you may need in some of your projects.</p> | |
| <section id="underscores-in-tags" class="level3"> | |
| <h3 class="anchored" data-anchor-id="underscores-in-tags">Underscores in tags</h3> | |
| <p>Now that we understand how FastHTML generates components, we can create our own in all kinds of ways. For example, maybe we need a weird HTML tag that uses underscores. FastHTML replaces <code>_</code> with <code>-</code> in tags because underscores in tags are highly unusual and rarely what you want, though it does come up rarely.</p> | |
| <div id="cell-18" class="cell"> | |
| <div class="sourceCode cell-code" id="cb9"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="kw">def</span> tag_with_underscores(<span class="op">*</span>c, target_id<span class="op">=</span><span class="va">None</span>, <span class="op">**</span>kwargs): </span> | |
| <span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> ft_hx(<span class="st">'tag_with_underscores'</span>, <span class="op">*</span>c, target_id<span class="op">=</span>target_id, <span class="op">**</span>kwargs)</span> | |
| <span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a>tag_with_underscores()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| <div class="cell-output cell-output-display cell-output-markdown"> | |
| <div class="sourceCode" id="cb10"><pre class="sourceCode html code-with-copy"><code class="sourceCode html"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="dt"><</span><span class="kw">tag_with_underscores</span><span class="dt">></</span><span class="kw">tag_with_underscores</span><span class="dt">></span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| </div> | |
| </section> | |
| <section id="symbols-ie-in-tags" class="level3"> | |
| <h3 class="anchored" data-anchor-id="symbols-ie-in-tags">Symbols (ie @) in tags</h3> | |
| <p>Sometimes you may need to use a tag that uses characters that are not allowed in function names in python (again, very unusual).</p> | |
| <div id="cell-21" class="cell"> | |
| <div class="sourceCode cell-code" id="cb11"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="kw">def</span> tag_with_AtSymbol(<span class="op">*</span>c, target_id<span class="op">=</span><span class="va">None</span>, <span class="op">**</span>kwargs): </span> | |
| <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> ft_hx(<span class="st">'tag-with-@symbol'</span>, <span class="op">*</span>c, target_id<span class="op">=</span>target_id, <span class="op">**</span>kwargs)</span> | |
| <span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a></span> | |
| <span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>tag_with_AtSymbol()</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| <div class="cell-output cell-output-display cell-output-markdown"> | |
| <div class="sourceCode" id="cb12"><pre class="sourceCode html code-with-copy"><code class="sourceCode html"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="dt"><</span><span class="kw">tag-with-</span><span class="er">@</span><span class="ot">symbol</span><span class="dt">></</span><span class="kw">tag-with-</span><span class="er">@symbol</span><span class="dt">></span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| </div> | |
| </section> | |
| <section id="symbols-ie-in-tag-attributes" class="level3"> | |
| <h3 class="anchored" data-anchor-id="symbols-ie-in-tag-attributes">Symbols (ie @) in tag attributes</h3> | |
| <p>It also may be that an argument in an HTML tag uses characters that can’t be used in python arguments. To handle these you can define those args using a dictionary.</p> | |
| <div id="cell-24" class="cell"> | |
| <div class="sourceCode cell-code" id="cb13"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>Div(normal_arg<span class="op">=</span><span class="st">'normal stuff'</span>,<span class="op">**</span>{<span class="st">'notNormal:arg:with_varing@symbols!'</span>:<span class="st">'123'</span>})</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| <div class="cell-output cell-output-display cell-output-markdown"> | |
| <div class="sourceCode" id="cb14"><pre class="sourceCode html code-with-copy"><code class="sourceCode html"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="dt"><</span><span class="kw">div</span><span class="ot"> normal-arg</span><span class="op">=</span><span class="st">"normal stuff"</span><span class="ot"> notnormal:arg:with_varing</span><span class="er">@</span><span class="ot">symbols</span><span class="er">!</span><span class="op">=</span><span class="st">"123"</span><span class="dt">></</span><span class="kw">div</span><span class="dt">></span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div> | |
| </div> | |
| </div> | |
| </section> | |
| </section> | |
| </main> <!-- /main --> | |
| <script id="quarto-html-after-body" type="application/javascript"> | |
| window.document.addEventListener("DOMContentLoaded", function (event) { | |
| const toggleBodyColorMode = (bsSheetEl) => { | |
| const mode = bsSheetEl.getAttribute("data-mode"); | |
| const bodyEl = window.document.querySelector("body"); | |
| if (mode === "dark") { | |
| bodyEl.classList.add("quarto-dark"); | |
| bodyEl.classList.remove("quarto-light"); | |
| } else { | |
| bodyEl.classList.add("quarto-light"); | |
| bodyEl.classList.remove("quarto-dark"); | |
| } | |
| } | |
| const toggleBodyColorPrimary = () => { | |
| const bsSheetEl = window.document.querySelector("link#quarto-bootstrap"); | |
| if (bsSheetEl) { | |
| toggleBodyColorMode(bsSheetEl); | |
| } | |
| } | |
| toggleBodyColorPrimary(); | |
| const icon = ""; | |
| const anchorJS = new window.AnchorJS(); | |
| anchorJS.options = { | |
| placement: 'right', | |
| icon: icon | |
| }; | |
| anchorJS.add('.anchored'); | |
| const isCodeAnnotation = (el) => { | |
| for (const clz of el.classList) { | |
| if (clz.startsWith('code-annotation-')) { | |
| return true; | |
| } | |
| } | |
| return false; | |
| } | |
| const onCopySuccess = function(e) { | |
| // button target | |
| const button = e.trigger; | |
| // don't keep focus | |
| button.blur(); | |
| // flash "checked" | |
| button.classList.add('code-copy-button-checked'); | |
| var currentTitle = button.getAttribute("title"); | |
| button.setAttribute("title", "Copied!"); | |
| let tooltip; | |
| if (window.bootstrap) { | |
| button.setAttribute("data-bs-toggle", "tooltip"); | |
| button.setAttribute("data-bs-placement", "left"); | |
| button.setAttribute("data-bs-title", "Copied!"); | |
| tooltip = new bootstrap.Tooltip(button, | |
| { trigger: "manual", | |
| customClass: "code-copy-button-tooltip", | |
| offset: [0, -8]}); | |
| tooltip.show(); | |
| } | |
| setTimeout(function() { | |
| if (tooltip) { | |
| tooltip.hide(); | |
| button.removeAttribute("data-bs-title"); | |
| button.removeAttribute("data-bs-toggle"); | |
| button.removeAttribute("data-bs-placement"); | |
| } | |
| button.setAttribute("title", currentTitle); | |
| button.classList.remove('code-copy-button-checked'); | |
| }, 1000); | |
| // clear code selection | |
| e.clearSelection(); | |
| } | |
| const getTextToCopy = function(trigger) { | |
| const codeEl = trigger.previousElementSibling.cloneNode(true); | |
| for (const childEl of codeEl.children) { | |
| if (isCodeAnnotation(childEl)) { | |
| childEl.remove(); | |
| } | |
| } | |
| return codeEl.innerText; | |
| } | |
| const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', { | |
| text: getTextToCopy | |
| }); | |
| clipboard.on('success', onCopySuccess); | |
| if (window.document.getElementById('quarto-embedded-source-code-modal')) { | |
| const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', { | |
| text: getTextToCopy, | |
| container: window.document.getElementById('quarto-embedded-source-code-modal') | |
| }); | |
| clipboardModal.on('success', onCopySuccess); | |
| } | |
| var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//); | |
| var mailtoRegex = new RegExp(/^mailto:/); | |
| var filterRegex = new RegExp("https:\/\/www\.fastht\.ml\/docs\/"); | |
| var isInternal = (href) => { | |
| return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href); | |
| } | |
| // Inspect non-navigation links and adorn them if external | |
| var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)'); | |
| for (var i=0; i<links.length; i++) { | |
| const link = links[i]; | |
| if (!isInternal(link.href)) { | |
| // undo the damage that might have been done by quarto-nav.js in the case of | |
| // links that we want to consider external | |
| if (link.dataset.originalHref !== undefined) { | |
| link.href = link.dataset.originalHref; | |
| } | |
| } | |
| } | |
| function tippyHover(el, contentFn, onTriggerFn, onUntriggerFn) { | |
| const config = { | |
| allowHTML: true, | |
| maxWidth: 500, | |
| delay: 100, | |
| arrow: false, | |
| appendTo: function(el) { | |
| return el.parentElement; | |
| }, | |
| interactive: true, | |
| interactiveBorder: 10, | |
| theme: 'quarto', | |
| placement: 'bottom-start', | |
| }; | |
| if (contentFn) { | |
| config.content = contentFn; | |
| } | |
| if (onTriggerFn) { | |
| config.onTrigger = onTriggerFn; | |
| } | |
| if (onUntriggerFn) { | |
| config.onUntrigger = onUntriggerFn; | |
| } | |
| window.tippy(el, config); | |
| } | |
| const noterefs = window.document.querySelectorAll('a[role="doc-noteref"]'); | |
| for (var i=0; i<noterefs.length; i++) { | |
| const ref = noterefs[i]; | |
| tippyHover(ref, function() { | |
| // use id or data attribute instead here | |
| let href = ref.getAttribute('data-footnote-href') || ref.getAttribute('href'); | |
| try { href = new URL(href).hash; } catch {} | |
| const id = href.replace(/^#\/?/, ""); | |
| const note = window.document.getElementById(id); | |
| if (note) { | |
| return note.innerHTML; | |
| } else { | |
| return ""; | |
| } | |
| }); | |
| } | |
| const xrefs = window.document.querySelectorAll('a.quarto-xref'); | |
| const processXRef = (id, note) => { | |
| // Strip column container classes | |
| const stripColumnClz = (el) => { | |
| el.classList.remove("page-full", "page-columns"); | |
| if (el.children) { | |
| for (const child of el.children) { | |
| stripColumnClz(child); | |
| } | |
| } | |
| } | |
| stripColumnClz(note) | |
| if (id === null || id.startsWith('sec-')) { | |
| // Special case sections, only their first couple elements | |
| const container = document.createElement("div"); | |
| if (note.children && note.children.length > 2) { | |
| container.appendChild(note.children[0].cloneNode(true)); | |
| for (let i = 1; i < note.children.length; i++) { | |
| const child = note.children[i]; | |
| if (child.tagName === "P" && child.innerText === "") { | |
| continue; | |
| } else { | |
| container.appendChild(child.cloneNode(true)); | |
| break; | |
| } | |
| } | |
| if (window.Quarto?.typesetMath) { | |
| window.Quarto.typesetMath(container); | |
| } | |
| return container.innerHTML | |
| } else { | |
| if (window.Quarto?.typesetMath) { | |
| window.Quarto.typesetMath(note); | |
| } | |
| return note.innerHTML; | |
| } | |
| } else { | |
| // Remove any anchor links if they are present | |
| const anchorLink = note.querySelector('a.anchorjs-link'); | |
| if (anchorLink) { | |
| anchorLink.remove(); | |
| } | |
| if (window.Quarto?.typesetMath) { | |
| window.Quarto.typesetMath(note); | |
| } | |
| if (note.classList.contains("callout")) { | |
| return note.outerHTML; | |
| } else { | |
| return note.innerHTML; | |
| } | |
| } | |
| } | |
| for (var i=0; i<xrefs.length; i++) { | |
| const xref = xrefs[i]; | |
| tippyHover(xref, undefined, function(instance) { | |
| instance.disable(); | |
| let url = xref.getAttribute('href'); | |
| let hash = undefined; | |
| if (url.startsWith('#')) { | |
| hash = url; | |
| } else { | |
| try { hash = new URL(url).hash; } catch {} | |
| } | |
| if (hash) { | |
| const id = hash.replace(/^#\/?/, ""); | |
| const note = window.document.getElementById(id); | |
| if (note !== null) { | |
| try { | |
| const html = processXRef(id, note.cloneNode(true)); | |
| instance.setContent(html); | |
| } finally { | |
| instance.enable(); | |
| instance.show(); | |
| } | |
| } else { | |
| // See if we can fetch this | |
| fetch(url.split('#')[0]) | |
| .then(res => res.text()) | |
| .then(html => { | |
| const parser = new DOMParser(); | |
| const htmlDoc = parser.parseFromString(html, "text/html"); | |
| const note = htmlDoc.getElementById(id); | |
| if (note !== null) { | |
| const html = processXRef(id, note); | |
| instance.setContent(html); | |
| } | |
| }).finally(() => { | |
| instance.enable(); | |
| instance.show(); | |
| }); | |
| } | |
| } else { | |
| // See if we can fetch a full url (with no hash to target) | |
| // This is a special case and we should probably do some content thinning / targeting | |
| fetch(url) | |
| .then(res => res.text()) | |
| .then(html => { | |
| const parser = new DOMParser(); | |
| const htmlDoc = parser.parseFromString(html, "text/html"); | |
| const note = htmlDoc.querySelector('main.content'); | |
| if (note !== null) { | |
| // This should only happen for chapter cross references | |
| // (since there is no id in the URL) | |
| // remove the first header | |
| if (note.children.length > 0 && note.children[0].tagName === "HEADER") { | |
| note.children[0].remove(); | |
| } | |
| const html = processXRef(null, note); | |
| instance.setContent(html); | |
| } | |
| }).finally(() => { | |
| instance.enable(); | |
| instance.show(); | |
| }); | |
| } | |
| }, function(instance) { | |
| }); | |
| } | |
| let selectedAnnoteEl; | |
| const selectorForAnnotation = ( cell, annotation) => { | |
| let cellAttr = 'data-code-cell="' + cell + '"'; | |
| let lineAttr = 'data-code-annotation="' + annotation + '"'; | |
| const selector = 'span[' + cellAttr + '][' + lineAttr + ']'; | |
| return selector; | |
| } | |
| const selectCodeLines = (annoteEl) => { | |
| const doc = window.document; | |
| const targetCell = annoteEl.getAttribute("data-target-cell"); | |
| const targetAnnotation = annoteEl.getAttribute("data-target-annotation"); | |
| const annoteSpan = window.document.querySelector(selectorForAnnotation(targetCell, targetAnnotation)); | |
| const lines = annoteSpan.getAttribute("data-code-lines").split(","); | |
| const lineIds = lines.map((line) => { | |
| return targetCell + "-" + line; | |
| }) | |
| let top = null; | |
| let height = null; | |
| let parent = null; | |
| if (lineIds.length > 0) { | |
| //compute the position of the single el (top and bottom and make a div) | |
| const el = window.document.getElementById(lineIds[0]); | |
| top = el.offsetTop; | |
| height = el.offsetHeight; | |
| parent = el.parentElement.parentElement; | |
| if (lineIds.length > 1) { | |
| const lastEl = window.document.getElementById(lineIds[lineIds.length - 1]); | |
| const bottom = lastEl.offsetTop + lastEl.offsetHeight; | |
| height = bottom - top; | |
| } | |
| if (top !== null && height !== null && parent !== null) { | |
| // cook up a div (if necessary) and position it | |
| let div = window.document.getElementById("code-annotation-line-highlight"); | |
| if (div === null) { | |
| div = window.document.createElement("div"); | |
| div.setAttribute("id", "code-annotation-line-highlight"); | |
| div.style.position = 'absolute'; | |
| parent.appendChild(div); | |
| } | |
| div.style.top = top - 2 + "px"; | |
| div.style.height = height + 4 + "px"; | |
| div.style.left = 0; | |
| let gutterDiv = window.document.getElementById("code-annotation-line-highlight-gutter"); | |
| if (gutterDiv === null) { | |
| gutterDiv = window.document.createElement("div"); | |
| gutterDiv.setAttribute("id", "code-annotation-line-highlight-gutter"); | |
| gutterDiv.style.position = 'absolute'; | |
| const codeCell = window.document.getElementById(targetCell); | |
| const gutter = codeCell.querySelector('.code-annotation-gutter'); | |
| gutter.appendChild(gutterDiv); | |
| } | |
| gutterDiv.style.top = top - 2 + "px"; | |
| gutterDiv.style.height = height + 4 + "px"; | |
| } | |
| selectedAnnoteEl = annoteEl; | |
| } | |
| }; | |
| const unselectCodeLines = () => { | |
| const elementsIds = ["code-annotation-line-highlight", "code-annotation-line-highlight-gutter"]; | |
| elementsIds.forEach((elId) => { | |
| const div = window.document.getElementById(elId); | |
| if (div) { | |
| div.remove(); | |
| } | |
| }); | |
| selectedAnnoteEl = undefined; | |
| }; | |
| // Handle positioning of the toggle | |
| window.addEventListener( | |
| "resize", | |
| throttle(() => { | |
| elRect = undefined; | |
| if (selectedAnnoteEl) { | |
| selectCodeLines(selectedAnnoteEl); | |
| } | |
| }, 10) | |
| ); | |
| function throttle(fn, ms) { | |
| let throttle = false; | |
| let timer; | |
| return (...args) => { | |
| if(!throttle) { // first call gets through | |
| fn.apply(this, args); | |
| throttle = true; | |
| } else { // all the others get throttled | |
| if(timer) clearTimeout(timer); // cancel #2 | |
| timer = setTimeout(() => { | |
| fn.apply(this, args); | |
| timer = throttle = false; | |
| }, ms); | |
| } | |
| }; | |
| } | |
| // Attach click handler to the DT | |
| const annoteDls = window.document.querySelectorAll('dt[data-target-cell]'); | |
| for (const annoteDlNode of annoteDls) { | |
| annoteDlNode.addEventListener('click', (event) => { | |
| const clickedEl = event.target; | |
| if (clickedEl !== selectedAnnoteEl) { | |
| unselectCodeLines(); | |
| const activeEl = window.document.querySelector('dt[data-target-cell].code-annotation-active'); | |
| if (activeEl) { | |
| activeEl.classList.remove('code-annotation-active'); | |
| } | |
| selectCodeLines(clickedEl); | |
| clickedEl.classList.add('code-annotation-active'); | |
| } else { | |
| // Unselect the line | |
| unselectCodeLines(); | |
| clickedEl.classList.remove('code-annotation-active'); | |
| } | |
| }); | |
| } | |
| const findCites = (el) => { | |
| const parentEl = el.parentElement; | |
| if (parentEl) { | |
| const cites = parentEl.dataset.cites; | |
| if (cites) { | |
| return { | |
| el, | |
| cites: cites.split(' ') | |
| }; | |
| } else { | |
| return findCites(el.parentElement) | |
| } | |
| } else { | |
| return undefined; | |
| } | |
| }; | |
| var bibliorefs = window.document.querySelectorAll('a[role="doc-biblioref"]'); | |
| for (var i=0; i<bibliorefs.length; i++) { | |
| const ref = bibliorefs[i]; | |
| const citeInfo = findCites(ref); | |
| if (citeInfo) { | |
| tippyHover(citeInfo.el, function() { | |
| var popup = window.document.createElement('div'); | |
| citeInfo.cites.forEach(function(cite) { | |
| var citeDiv = window.document.createElement('div'); | |
| citeDiv.classList.add('hanging-indent'); | |
| citeDiv.classList.add('csl-entry'); | |
| var biblioDiv = window.document.getElementById('ref-' + cite); | |
| if (biblioDiv) { | |
| citeDiv.innerHTML = biblioDiv.innerHTML; | |
| } | |
| popup.appendChild(citeDiv); | |
| }); | |
| return popup.innerHTML; | |
| }); | |
| } | |
| } | |
| }); | |
| </script> | |
| </div> <!-- /content --> | |
| <footer class="footer"><div class="nav-footer"><div class="nav-footer-center"><div class="toc-actions d-sm-block d-md-none"><ul><li><a href="https://github.com/AnswerDotAI/fasthtml/issues/new" class="toc-action"><i class="bi bi-github"></i>Report an issue</a></li></ul></div></div></div></footer></body></html> |