Merge pull request #753 from pydanny/improve-custom-components-docs

Improvements to the custom components docs

Author: jph00

nbs/ref/defining_xt_component.ipynb

@@ -32,45 +32,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## NotStr\n",
-    "\n",
-    "The first way is to use the `NotStr` 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 `NotStr` as the out-of-the-box components."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from fasthtml.common import NotStr,Div, to_xml"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "<div></div>\n"
-     ]
-    }
-   ],
-   "source": [
-    "div_NotStr = NotStr('<div></div>') \n",
-    "print(div_NotStr)"
+    "## Automatic Creation"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Automatic Creation\n",
-    "\n",
-    "The next (and better) approach is to let FastHTML generate the component function for you.  As you can see in our `assert` this creates a function that creates the HTML just as we wanted.  This works even though there is not a `Some_never_before_used_tag` function in the `fasthtml.components` source code (you can verify this yourself by looking at the source code).  \n",
+    "The first (and in most cases the best) approach is to let FastHTML generate the component function for you.  As you can see in our `assert` this creates a function that creates the HTML just as we wanted.  This works even though there is not a `Some_never_before_used_tag` function in the `fasthtml.components` source code (you can verify this yourself by looking at the source code).  \n",
     "\n",
     ":::{.callout-tip}\n",
     "Typically these tags are needed because a CSS or Javascript library created a new XML tag that isn't default HTML.  For example the `zero-md` javascript library looks for a `<zero-md></zero-md>` tag to know what to run its javascript code on.  Most CSS libraries work by creating styling based on the `class` attribute, but they can also apply styling to an arbitrary HTML tag that they made up.\n",
@@ -108,52 +77,25 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Manual Creation"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The automatic creation isn't magic.  It's just calling a python function `__getattr__` and you can call it yourself to get the same result."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import fasthtml\n",
-    "\n",
-    "auto_called = fasthtml.components.Some_never_before_used_tag()\n",
-    "manual_called = fasthtml.components.__getattr__('Some_never_before_used_tag')()\n",
+    ":::{.callout-tip}\n",
+    "In a module `__getattr__` is called to get an attribute.  In `fasthtml.components`, the `__getattr__` is set to create components automatically for you.\n",
     "\n",
-    "# Proving they generate the same xml\n",
-    "assert to_xml(auto_called) == to_xml(manual_called)"
+    "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 (`__init__`  is probably the most common one).\n",
+    ":::"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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 `___getattr__` 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.\n",
-    "\n"
+    "## Manual Creation"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    ":::{.callout-tip}\n",
-    "\n",
-    "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 (`__init__`  is probably the most common one).\n",
-    "\n",
-    "In a module `__getattr__` is called to get an attribute.  In `fasthtml.components`, this is defined to create components automatically for you.\n",
-    ":::\n",
-    "\n",
-    "\n",
-    "For example if you want a component that creates `<path></path>` that doesn't conflict names with `pathlib.Path` 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 `ft_hx` function to do that differently than the default."
+    "If you want a component that creates `<path></path>` that doesn't conflict names with `pathlib.Path` 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 `ft_hx` function to do that differently than the default."
    ]
   },
   {
@@ -186,6 +128,13 @@
     "ft_path()\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Special Cases"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -232,7 +181,7 @@
     "def tag_with_underscores(*c, target_id=None, **kwargs): \n",
     "    return ft_hx('tag_with_underscores', *c, target_id=target_id, **kwargs)\n",
     "\n",
-    "tag_with_underscores()\n"
+    "tag_with_underscores()"
    ]
   },
   {
@@ -271,7 +220,6 @@
     }
    ],
    "source": [
-    "\n",
     "def tag_with_AtSymbol(*c, target_id=None, **kwargs): \n",
     "    return ft_hx('tag-with-@symbol', *c, target_id=target_id, **kwargs)\n",
     "\n",
@@ -292,6 +240,15 @@
     "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."
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fasthtml.common import Div"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -317,6 +274,59 @@
    "source": [
     "Div(normal_arg='normal stuff',**{'notNormal:arg:with_varing@symbols!':'123'})"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## In Desperation: NotStr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "An uncommon method is to use the `NotStr` class writing the HTML tag as a string.  It works as a one-off for a quickfix but quickly becomes harder to work with as complexity grows.  However we can see that you can with some effort generate a similar result with `to_xml` using `NotStr` as the out-of-the-box components.\n",
+    "\n",
+    "Try everything else before using `NotStr` and if you must use it we recommend returning later and fixing it to use one of the above techniques."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fasthtml.common import NotStr,to_xml"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'<div>I look like a string but render with to_xml</div>'"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "div_NotStr = NotStr('<div>I look like a string but render with to_xml</div>') \n",
+    "to_xml(div_NotStr)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {