finish off your firt component section

Author: rmorshea

docs/source/_examples/creating_interfaces/bad_conditional_todo_list.py

@@ -0,0 +1,24 @@
+from idom import component, html, run
+
+
+@component
+def Item(name, done):
+    if done:
+        return html.li(name, " ✔")
+    else:
+        return html.li(name)
+
+
+@component
+def TodoList():
+    return html.section(
+        html.h1("My Todo List"),
+        html.ul(
+            Item("Find a cool problem to solve", done=True),
+            Item("Build an app to solve it", done=True),
+            Item("Share that app with the world!", done=False),
+        ),
+    )
+
+
+run(TodoList)

docs/source/_examples/creating_interfaces/good_conditional_todo_list.py

@@ -0,0 +1,21 @@
+from idom import component, html, run
+
+
+@component
+def Item(name, done):
+    return html.li(name, "" if done else " ✔")
+
+
+@component
+def TodoList():
+    return html.section(
+        html.h1("My Todo List"),
+        html.ul(
+            Item("Find a cool problem to solve", done=True),
+            Item("Build an app to solve it", done=True),
+            Item("Share that app with the world!", done=False),
+        ),
+    )
+
+
+run(TodoList)

docs/source/_examples/creating_interfaces/nested_photos.py

@@ -5,7 +5,7 @@
 def Photo():
     return html.img(
         {
-            "src": "https://i.pinimg.com/564x/d6/96/c4/d696c4d3db31609c1abb05c52f305ec1.jpg",
+            "src": "https://picsum.photos/id/274/500/300",
             "style": {"width": "30%"},
             "alt": "Ray Charles",
         }

docs/source/_examples/creating_interfaces/parametrized_photos.py

@@ -0,0 +1,25 @@
+from idom import component, html, run
+
+
+@component
+def Photo(alt_text, image_id):
+    return html.img(
+        {
+            "src": f"https://picsum.photos/id/{image_id}/500/300",
+            "style": {"width": "50%"},
+            "alt": alt_text,
+        }
+    )
+
+
+@component
+def Gallery():
+    return html.section(
+        html.h1("Photo Gallery"),
+        Photo("Landscape", image_id=830),
+        Photo("City", image_id=274),
+        Photo("Puppy", image_id=237),
+    )
+
+
+run(Gallery)

docs/source/_examples/creating_interfaces/simple_photo.py

@@ -5,9 +5,9 @@
 def Photo():
     return html.img(
         {
-            "src": "https://i.pinimg.com/564x/d6/96/c4/d696c4d3db31609c1abb05c52f305ec1.jpg",
-            "style": {"width": "30%"},
-            "alt": "Ray Charles",
+            "src": "https://picsum.photos/id/237/500/300",
+            "style": {"width": "50%"},
+            "alt": "Puppy",
         }
     )
 

docs/source/_examples/creating_interfaces/static_todo_list.py

@@ -0,0 +1,21 @@
+from idom import component, html, run
+
+
+@component
+def Item(name, done):
+    return html.li(name)
+
+
+@component
+def TodoList():
+    return html.section(
+        html.h1("My Todo List"),
+        html.ul(
+            Item("Find a cool problem to solve", done=True),
+            Item("Build an app to solve it", done=True),
+            Item("Share that app with the world!", done=False),
+        ),
+    )
+
+
+run(TodoList)

docs/source/_examples/creating_interfaces/todo_list.py

@@ -79,9 +79,9 @@ to specify a URL to its ``src`` and use some ``style`` to modify and position it
 .. code-block:: html
 
     <img
-        src="https://i.pinimg.com/564x/29/66/4d/29664d24bc793085a7671d7fc02a33f4.jpg"
+        src="https://picsum.photos/id/237/500/300"
         style="width: 50%; margin-left: 25%;"
-        alt="Martha Argerich"
+        alt="Billie Holiday"
     />
 
 In IDOM we add these attributes to elements using dictionaries. There are some notable
@@ -93,18 +93,18 @@ Additionally, instead of specifying ``style`` using a string, we use a dictionar
 
     html.img(
         {
-            "src": "https://i.pinimg.com/564x/29/66/4d/29664d24bc793085a7671d7fc02a33f4.jpg
+            "src": "https://picsum.photos/id/237/500/300",
             "style": {"width": "50%", "marginLeft": "25%"},
-            "alt": "Martha Argerich",
+            "alt": "Billie Holiday",
         }
     )
 
 .. raw:: html
 
     <img
-        src="https://i.pinimg.com/564x/29/66/4d/29664d24bc793085a7671d7fc02a33f4.jpg"
+        src="https://picsum.photos/id/237/500/300"
         style="width: 50%; margin-left: 25%;"
-        alt="Martha Argerich"
+        alt="Billie Holiday"
     />
 
 

docs/source/creating-interfaces/conditional-rendering.rst

@@ -6,8 +6,6 @@ Creating Interfaces
 
     html-with-idom
     your-first-components
-    parametrizing-components
-    conditional-rendering
     dynamic-element-children
 
 .. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
@@ -21,35 +19,19 @@ Creating Interfaces
             :link: html-with-idom
             :link-type: doc
 
-            Learn how to construct HTML layouts with IDOM and the underlying data
-            structure we use to represent them.
+            Learn how to construct HTML layouts with IDOM.
 
         .. grid-item-card:: :octicon:`package` Your First Components
             :link: your-first-components
             :link-type: doc
 
-            Discover what components are and why they're one of IDOM's foundational
-            concepts.
-
-        .. grid-item-card:: :octicon:`plug` Parametrizing Components
-            :link: parametrizing-components
-            :link-type: doc
-
-            Leverage the reusability of components by passing them arguments
-
-        .. grid-item-card:: :octicon:`code-square` Conditional Rendering
-            :link: conditional-rendering
-            :link-type: doc
-
-            Use what you've learned so far to render display different views depending
-            on a what a component's inputs are.
+            Discover how to define and use components.
 
         .. grid-item-card:: :octicon:`versions` Dynamic Element Children
             :link: dynamic-element-children
             :link-type: doc
 
-            Understand how to correctly render using lists of child elements that
-            may change in length or order
+            Correctly render lists of child elements that may change in length or order.
 
 IDOM is a Python package for making user interfaces (UI). These interfaces are built
 from small elements of functionality like buttons text and images. IDOM allows you to
@@ -112,36 +94,9 @@ create them we need to add an ``@component`` `decorator
 <https://realpython.com/primer-on-python-decorators/>`__. To see what this looks like in
 practice we'll put the todo list HTML from above into a component:
 
-.. example:: creating_interfaces.static_todo_list
+.. example:: creating_interfaces.simple_photo
     :activate-result:
 
-If you explore a little bit on your own you'll find that, when called, functions which
-are decorated in this way don't return what you might initially expect:
-
-.. testsetup::
-
-    from idom import ComponentType, component, html
-
-    @idom.component
-    def App():
-        # doesn't matter what we return here
-        return ...
-
-.. testcode::
-
-    from idom import ComponentType
-
-    assert isinstance(App(), ComponentType)
-
-.. card::
-    :link: html-with-idom
-    :link-type: doc
-
-    :octicon:`book` Read More
-    ^^^^^^^^^^^^^^^^^^^^^^^^^
-
-    Discover what components are and why they're one of IDOM's foundational concepts.
-
 
 Section 3: Parametrizing Components
 -----------------------------------

docs/source/creating-interfaces/html-with-idom.rst

@@ -11,16 +11,11 @@ components can then be reused throughout your application.
 Defining a Component
 --------------------
 
-At their core, components are just a normal Python functions that return HTML. There's
-only two special things which we'll concer ourselves with there:
-
-- We need to add a ``@component`` `decorator
-  <https://realpython.com/primer-on-python-decorators/>`__
-  to component function.
-
-- By convention, we name component functions like classes - with ``CamelCase``.
-
-So for example, if we wanted write and then :ref:`display <Running IDOM>` a ``Photo``
+At their core, components are just normal Python functions that return HTML. To define a
+component you just need to add a ``@component`` `decorator
+<https://realpython.com/primer-on-python-decorators/>`__ to a function. Then, by
+convention, we name component functions like classes - with ``CamelCase``. So for
+example, if we wanted to write and then :ref:`display <Running IDOM>` a ``Photo``
 component we might write:
 
 .. example:: creating_interfaces.simple_photo
@@ -40,7 +35,49 @@ component we might write:
 Using a Component
 -----------------
 
-Having defined our ``Photo`` component we can now nest it inside of other components:
+Having defined our ``Photo`` component we can now nest it inside of other components. We
+can define a "parent" ``Gallery`` component that returns one or more ``Profile``
+components. This is part of what makes components so powerful - you can define a
+component once and use it wherever and however you need to:
 
 .. example:: creating_interfaces.nested_photos
     :activate-result:
+
+
+Parametrizing Components
+------------------------
+
+Since components are just regular functions, you can add parameters to them. This allows
+parent components to pass information to child components. Where standard HTML elements
+are parametrized by dictionaries, since components behave like typical functions you can
+give them positional and keyword arguments as you would normally:
+
+.. example:: creating_interfaces.parametrized_photos
+    :activate-result:
+
+
+Conditional Rendering
+---------------------
+
+Your components will often need to display different things depending on different
+conditions. Let's imagine that we had a basic todo list where only some of the items
+have been completed. Below we have a basic implementation for such a list except that
+the ``Item`` component doesn't change based on whether it's ``done``:
+
+.. example:: creating_interfaces.todo_list
+    :activate-result:
+
+Let's imagine that we want to add a ✔ to the items which have been marked ``done=True``.
+One way to do this might be to write an ``if`` statement where we return one ``li``
+element if the item is ``done`` and a different one if it's not:
+
+.. example:: creating_interfaces.bad_conditional_todo_list
+    :activate-result:
+
+As you can see this accomplishes our goal! However, notice how similar ``html.li(name, "
+✔")`` and ``html.li(name)`` are. While in this case it isn't especially harmful, we
+could make our code a little easier to read and maintain by using an "inline" ``if``
+statement.
+
+.. example:: creating_interfaces.good_conditional_todo_list
+    :activate-result:

docs/source/creating-interfaces/index.rst

@@ -4,6 +4,7 @@ Managing State
 .. toctree::
     :hidden:
 
+    keeping-components-pure
     logical-flow-of-state
     structuring-your-state
     shared-component-state

docs/source/creating-interfaces/parametrizing-components.rst

@@ -0,0 +1,4 @@
+Keeping Components Pure
+=======================
+
+Under construction :)