DEV Community: Jim Grimes

Flask-SQLAlchemy Many-to-Many Relationships: Association Tables and Association Objects

Jim Grimes — Tue, 21 Nov 2023 21:59:01 +0000

SQLAlchemy provides two tools for managing many-to-many relationships: Association Tables and Association Objects. This blog will review how to use association tables and association objects in a Flask application using the Flask-SQLAlchemy extension.

Association Tables

An association table, like a basic join table in SQLlite, is a database table that is used to keep track of the relationships between two other tables. An association tables does not contain any information besides what is necessary to manage those relationships.

Say we have two models, Teacher and Student, that have a many-to-many relationship. Each teacher has many students, and each student has many teachers. Their relationship can be managed with an association table, teacher_students. The only columns that teacher_students contains are the columns that refer to the tables for Teacher and Student. teacher_students cannot be used to manage any additional information.

The relationship between Teacher and Student is created by making columns in teacher_students that contain foreign keys referring to the id columns of the Teacher and Student tables.

from flask_sqlalchemy import SQLAlchemy
from sqlalchemy import MetaData
from sqlalchemy.ext.associationproxy import association_proxy

metadata = MetaData(naming_convention={
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
})

db = SQLAlchemy(metadata=metadata)

teacher_students = db.Table(
    'teacher_students',
    metadata,
    db.Column('teacher_id', db.ForeignKey('teachers.id'), 
        primary_key=True),
    db.Column('student_id', db.ForeignKey('students.id'), 
        primary_key=True)
)

It isn't necessary to specify the data type of the columns in teacher_students because the type of data in each column is inferred from the type of data in the columns of the Teacher table and Student table.

Regarding the model columns that should be used in association table:

It is also recommended, though not in any way required by SQLAlchemy, that the columns which refer to the two entity tables are established within either a unique constraint or more commonly as the primary key constraint; this ensures that duplicate rows won’t be persisted within the table regardless of issues on the application side.
https://docs.sqlalchemy.org/en/20/orm/basic_relationships.html#many-to-many

To create the many-to-many relationship between Teacher and Student, each model is given a relationship() attribute that links them to each other. Teacher is given a students attribute and Student is given a teachers attribute. The connection between the models and teacher_students is provided by the secondary parameter in each model's relationship attribute, which points to the association table.

class Teacher(db.Model):
    __tablename__ = 'teachers'

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String)

    students = db.relationship('Student', secondary=teacher_students,
        back_populates='teachers')

    def __repr__(self):
        return f'<Teacher {self.id}>'

class Student(db.Model):
    __tablename__ = 'students'

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String)

    teachers = db.relationship('Teacher', secondary=teacher_students,     
        back_populates='students')

    def __repr__(self):
        return f'<Student {self.id}>'

Additional details and information about the secondary parameter can be found here:
https://docs.sqlalchemy.org/en/20/orm/relationship_api.html#sqlalchemy.orm.relationship.params.secondary

To see the students that a teacher has or the teachers that a student has, the students and teachers attributes can be called on instances of the Teacher and Student models:

>>> t1 = Teacher.query.first()
>>> t1
<Teacher 1>
>>> t1.students
[<Student 1>, <Student 3>, <Student 6>]

>>> s1 = Student.query.first()
>>> s1
<Student 1>
>>> s1.teachers
[<Teacher 1>, <Teacher 2>]

Association Objects

What if, instead of only keeping track of the relationships between Teacher and Student instances, we wanted the join table to also keep track of the exams that each teacher administers and each student takes. In that case, an association object would be used instead of an association table because it is necessary for the join table to hold extra information. In other words, when the join table needs to contain more columns than just the foreign keys from other tables, an association object should be used.

The association object pattern is a variant on many-to-many: it’s used when an association table contains additional columns beyond those which are foreign keys to the parent and child (or left and right) tables, columns which are most ideally mapped to their own ORM mapped class.
https://docs.sqlalchemy.org/en/20/orm/basic_relationships.html#association-object

In the example above, there are models for Teacher and Student. To create an association object that keeps track of exams, along with the relationships between Teacher and Student instances, there needs to be a third model, Exam, which acts as the association object. Like the association table used above, the Exam model's table is still given columns to keep track of the foreign keys of the many-to-many relationship models, but it can also contain columns for whatever other information is needed to be stored in the table.

class Exam(db.Model):
    __tablename__ = 'exams_table'

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String)

    teacher_id = db.Column(db.Integer, db.ForeignKey('teachers.id'))
    student_id = db.Column(db.Integer, db.ForeignKey('students.id'))

    teacher = db.relationship('Teacher', back_populates='exams')
    student = db.relationship('Student', back_populates='exams')

    def __repr__(self):
        return f'<Exam {self.id}>'

Instead of the Teacher and Student models having a direct, many-to-many relationship, they will now have one-to-many relationships with the Exam association object.

In the association object pattern, the relationship.secondary parameter is not used; instead, a class is mapped directly to the association table. Two individual relationship() constructs then link first the parent side to the mapped association class via one to many, and then the mapped association class to the child side via many-to-one, to form a uni-directional association object relationship from parent, to association, to child. For a bi-directional relationship, four relationship() constructs are used to link the mapped association class to both parent and child in both directions.
https://docs.sqlalchemy.org/en/20/orm/basic_relationships.html#association-object

Instead of Teacher having a students attribute, it has an exams attribute, while the Student model has its own exams attribute.

class Teacher(db.Model):
    __tablename__ = 'teachers'

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String)

    exams = db.relationship('Exam', back_populates='teacher')

    students = association_proxy('exams', 'student')

    def __repr__(self):
        return f'<Teacher {self.id}>'

class Student(db.Model):
    __tablename__ = 'students'

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String)

    exams = db.relationship('Exam', back_populates='student')

    teachers = association_proxy('exams', 'teacher')

    def __repr__(self):
        return f'<Student {self.id}>'

This means that, unlike with an association table, the relationship between Teacher and Student cannot be accessed directly from a relationship object in either model. To make it easier to view the relationship between Teacher and Student now that they are linked by an association object, SQLAlchemy provides the Association Proxy tool.

To enhance the association object pattern such that direct access to the Association object is optional, SQLAlchemy provides the Association Proxy extension. This extension allows the configuration of attributes which will access two “hops” with a single access, one “hop” to the associated object, and a second to a target attribute.
https://docs.sqlalchemy.org/en/20/orm/basic_relationships.html#association-object

The association proxies in the above example (students in the Teacher model and teachers in the Student model) are provided (1) the name of the immediate target that is being used to manage the many-to-many relationship and (2) an attribute that is available in an instance of that target. In this example the immediate target is the relationship attribute exams, which is the variable used to establish the one-to-many relationships between the Teacher and Student models and the Exam association object. The attribute given to association_proxy() is the corresponding relationship variable in the Exam association object.

Now, the Teacher and Student models each have way to view the one-to-many relationship with the Exam association object, as well as a way to directly view the many-to-many relationships through the association proxies. Teacher's association proxy provides the value of the students associated with it while concealing, or skipping over, the association object.

>>> t1 = Teacher.query.first()
>>> t1
<Teacher 1>
>>> t1.exams
[<Exam 1>, <Exam 2>, <Exam 3>]
>>> t1.students
[<Student 1>, <Student 3>, <Student 6>]

By default, calling a model's association proxy attribute will return instances of the target object. So, calling Teacher.students returns a list of all the instances of Student that have a relationship with a particular instance of Teacher.

Additional information about using association proxies can be found here:

https://docs.sqlalchemy.org/en/20/orm/extensions/associationproxy.html

Using SQLite to Examine Data Relationships and Compare Tables

Jim Grimes — Mon, 13 Nov 2023 21:26:00 +0000

SQLite provides numerous ways to view and compare data across multiple tables. This blog will discuss SQLite queries that can be used to view data relationships:

INNER JOIN
LEFT JOIN
Using Multiple Join Operators

And SQLite queries that can be used to compare tables:

INTERSECT
UNION
UNION ALL
EXCEPT

Simple Select Queries

In order to illustrate how to use SELECT statements, I have created a database to keep track of garden plants and garden beds, which I refer to in the examples I use. The database has a plants table that contains information on the different garden plants, including the plant name, whether the plant requires full sun, and the time of year that the plant begins to bloom. The data in the plants table can be retrieved with a SELECT query:

SELECT * FROM plants;

id  name              full_sun  bloom      
--  ----------------  --------  -----------
1   Bee Balm          0         late spring
2   Petunia           1         summer     
3   Coneflower        0         summer     
4   Zinnia            1         late spring
5   Black-Eyed Susan  0         summer

In the full_sun column, the integers 1 and 0 are used to represent the Boolean values of 'true' and 'false', respectively.

To limit the result's columns to only include the plant's id number and name, the columns can be specified in the SELECT statement instead of using *:

SELECT id, name FROM plants;

id  name            
--  ----------------
1   Bee Balm        
2   Petunia         
3   Coneflower      
4   Zinnia          
5   Black-Eyed Susan

To limit the query result to only those rows that match a certain condition, a WHERE clause can be added to the query. For example, the following query would only select plants that do not require full sunlight:

SELECT * FROM plants WHERE full_sun IS 0;

id  name              full_sun  bloom      
--  ----------------  --------  -----------
1   Bee Balm          0         late spring
3   Coneflower        0         summer     
5   Black-Eyed Susan  0         summer

Select Queries With Join Operators

Retrieving data from a single table has its uses, but it does not allow me to easily see the relationships between data on multiple tables. You can use join statements to view data across multiple tables at the same time.

Our database also contains a table with information on garden beds:

beds

id  light        
--  -------------
1   full sun     
2   partial shade

A type of plant can be planted in multiple garden beds, and a garden bed can have multiple kinds of plants. To keep track of the relationships between plants and garden beds, there is a join table, called plant_beds:

plant_beds

id  plant_id  bed_id
--  --------  ------
1   1         2     
2   4         1     
3   3         2     
4   5         1     
5   1         1

The relationship between the plants, beds, and plant_beds tables can be visualized like this:

INNER JOIN

The INNER JOIN can be used to view the plants that correspond to each row in the plant_bed join table. SQLite treats the operators "INNER JOIN", "JOIN" and "," exactly the same, so they can be used interchangably.

SELECT plant_beds.id, plant_beds.plant_id, plants.name, plant_beds.bed_id
FROM plant_beds
INNER JOIN plants
ON plant_beds.plant_id = plants.id

id  plant_id  name              bed_id
--  --------  ----------------  ------
1   1         Bee Balm          2     
2   4         Zinnia            1     
3   3         Coneflower        2     
4   5         Black-Eyed Susan  1     
5   1         Bee Balm          1

Don't forget to include the ON statement in the query. The ON operator tells SQLite how the tables relate to each other. Without that instruction, SQLite will return every row from the plant_beds table matched with every row from the plants database:

SELECT plant_beds.id, plant_beds.plant_id, plants.name, plant_beds.bed_id
FROM plant_beds
INNER JOIN plants

id  plant_id  name              bed_id
--  --------  ----------------  ------
1   1         Bee Balm          2     
1   1         Petunia           2     
1   1         Coneflower        2     
1   1         Zinnia            2     
1   1         Black-Eyed Susan  2     
2   4         Bee Balm          1     
2   4         Petunia           1     
2   4         Coneflower        1     
2   4         Zinnia            1     
2   4         Black-Eyed Susan  1     
3   3         Bee Balm          2     
3   3         Petunia           2     
3   3         Coneflower        2     
3   3         Zinnia            2     
3   3         Black-Eyed Susan  2     
4   5         Bee Balm          1     
4   5         Petunia           1     
4   5         Coneflower        1     
4   5         Zinnia            1     
4   5         Black-Eyed Susan  1     
5   1         Bee Balm          1     
5   1         Petunia           1     
5   1         Coneflower        1     
5   1         Zinnia            1     
5   1         Black-Eyed Susan  1

This result includes Petunias in the response, even though they aren't currently associated with any beds in our plant_beds join table. So even though SQLite has returned information from both the plants table and the plant_beds table, the response does not represent the relationship between the two tables.

LEFT JOIN

The reponse to an INNER JOIN query only includes the rows from each table that have a match in the ON statement. SO, in the example above, Petunia is not include din the response because it is not included in the plant_beds table. In order to see all the rows from the left table or the right table, LEFT JOIN or LEFT OUTER JOIN should be used instead of INNER JOIN. The response from a LEFT JOIN query will include the same rows as an INNER JOIN query, as well as an extra row from each row in the left-hand table (or first table listed in the query) that does not have a mathing row in the right-hand table (the second table listed in the query). SQLite uses NULL as a default value for any column that does not have a value in the right-hand table

SELECT plant_beds.id, plant_beds.plant_id, plants.name, plant_beds.bed_id
FROM plant_beds
LEFT JOIN plants
ON plant_beds.plant_id = plants.id

id  plant_id  name              bed_id
--  --------  ----------------  ------
5   1         Bee Balm          1     
1   1         Bee Balm          2     
              Petunia                 
3   3         Coneflower        2     
2   4         Zinnia            1     
4   5         Black-Eyed Susan  1

As can be seen in this example, the LEFT JOIN query result includes the Petunia row from the plants table and uses NULL values, which appear as blank spaces, for the columns where there is no match for Petunia in the plant_beds table.

Using a JOIN Statement With More Than Two Tables

INNER JOIN and LEFT JOIN statements can be repeated in a query to produce a result that includes information from more than one table. For example, to see information from the plant_beds table as well as details from both the plants and beds tables, two INNER JOIN statements can be used.

SELECT plant_beds.id, plant_beds.plant_id, plants.name, plant_beds.bed_id, beds.light
FROM plant_beds
INNER JOIN plants
ON plant_beds.plant_id = plants.id
INNER JOIN beds
ON plant_beds.bed_id = beds.id

id  plant_id  name              bed_id  light        
--  --------  ----------------  ------  -------------
1   1         Bee Balm          2       partial shade
2   4         Zinnia            1       full sun     
3   3         Coneflower        2       partial shade
4   5         Black-Eyed Susan  1       full sun     
5   1         Bee Balm          1       full sun

Compound Select Statements

What if, instead of listing all plants in one table, the plants were sorted into multiple tables based on characteristics of each plant. I have made three more database tables to keep track of native plants, plants that are particularly attractive to bees, and plants that are likely to attract hummingbirds. Of course, there are native plants that are known as good choices for bees and hummingbirds, so the three tables will have some plants in common.

native_plants

id  name                full_sun  bloom      
--  ------------------  --------  -----------
1   Arrowwood Viburnum  0         late spring
2   Bee Balm            0         late spring
3   Black-Eyed Susan    0         summer     
4   Coneflower          0         summer     
5   Goldenrod           0         late summer

bee_plants

id  name        full_sun  bloom      
--  ----------  --------  -----------
1   Bee Balm    0         late spring
2   Lavender    1         summer     
3   Coneflower  0         summer     
4   Zinnia      1         late spring

hummingbird_plants

id  name             full_sun  bloom      
--  ---------------  --------  -----------
1   Petunia          1         summer     
2   Bee Balm         0         late spring
3   Cardinal Flower  1         mid summer 
4   Garden Phlox     0         summer

These tables can also be visualized like this:

Now that the plants are organized into multiple tables, it would be nice to be able to compare the tables to each other. This can be done with compound SELECT statements. Specifically, with the INTERSECT, UNION, UNION ALL, and EXCEPT operators.

INTERSECT

INTERSECT is used to obtain the columns and rows that tables have in common.

SELECT name, bloom FROM native_plants
INTERSECT
SELECT name, bloom FROM bee_plants

name        bloom      
----------  -----------
Bee Balm    late spring
Coneflower  summer

In order for the INTERSECT query to work, the columns in each SELECT column must match. The SELECT statements must have the same number of columns, and the columns must return the same type of information so that SQLite can compare each column value.

Note that in this example, the SELECT statement is not using id or * to retrieve the id column from the tables. While the native_plants, bee_plants, and hummingbird_plants tables have some plants in common, those plants do not have same id numbers in each table. In bee_plants, Bee Balm has an id of 1 and Coneflower has an id of 3, whereas in native_plants, Bee Balm has an id 2 and Coneflower has an id of 4. So if the query included the id column, the Bee Balm and Coneflower rows from each table would not match, and the INTERSECT operator would return no results.

UNION and UNION ALL

To get the information from multiple tables, regardless of whether the tables rows are the same in each table, use the UNION operator.

SELECT name, bloom FROM bee_plants
UNION
SELECT name, bloom FROM hummingbird_plants

name             bloom      
---------------  -----------
Bee Balm         late spring
Cardinal Flower  mid summer 
Coneflower       summer     
Garden Phlox     summer     
Lavender         summer     
Petunia          summer     
Zinnia           late spring

The UNION operator returned the rows from the bee_plants table and the rows from the hummingbird_plants table, and it automatically removed duplicate rows. In order to return every row from both tables, even if a row appears in each table, the UNION ALL operator can be used.

SELECT name, bloom FROM bee_plants
UNION ALL
SELECT name, bloom FROM hummingbird_plants

name             bloom      
---------------  -----------
Bee Balm         late spring
Lavender         summer     
Coneflower       summer     
Zinnia           late spring
Petunia          summer     
Bee Balm         late spring
Cardinal Flower  mid summer 
Garden Phlox     summer

Bee Balm appears twice in the result from the UNION ALL query because it exists in both the hummingbird_plants table and the bee_plants table.

EXCEPT

The EXCEPT operator can be used to retrieve rows from one table that do not appear in another table.

SELECT name, bloom FROM native_plants
EXCEPT
SELECT name, bloom FROM bee_plants

name                bloom      
------------------  -----------
Arrowwood Viburnum  late spring
Black-Eyed Susan    summer     
Goldenrod           late summer

Conclusion

Detailed documentation of SQLite's SELECT statements, including the operators discussed above and many other options for constructing SELECT statement, can be found on SQLite's website : https://sqlite.org/lang_select.html

Validating Inputs with Python Class Properties

Jim Grimes — Sun, 05 Nov 2023 22:04:16 +0000

Using Properties to Validate an Input at the Time a Class Instance is Created

The purpose of this blog post is to discuss some fundamental guidelines for creating class properties, namely: (1) the need to use getter and setter functions to validate inputs, and (2) the use of different variables for class properties and attributes. I did not have a clear understanding of those two things when I was first learning how to use class properties in python, so my attempts to use class properties were more frustrating than they needed to be. In my discussion of these points, I will refer to the following example:

Example 1:

class Person:

    def __init__(self, name):
        self.name = name

    def get_name(self):
        return self._name

    def set_name(self, new_name):
        if type(new_name) == str and len(new_name) > 0:
            self._name = new_name

    name = property(get_name, set_name)

Example 1 establishes a Person class which is meant to satisfy these conditions:

An instance of the Person class must be given a name at the time of creation.
The property functions are used to ensure that a person's name is a string containing at least one character.
Calling the person's name should return the person's name.

If an instance of the Person class is created with a valid name,

> p1 = Person("Frank")

calling the instance's name produces the following result:

> p1.name
'Frank'

Creating an instance of the Person class with an invalid name and then calling the instance's name produces an error:

> p2 = Person(2)
> p2.name
*** AttributeError: 'Person' object has no attribute '_name'

I am pointing out these conditions because you can find many other good examples of how to use class properties, but they will not necessarily work the same way that Example 1 does. When I was trying to learn about class properties, I tried to follow examples from various blogs but had difficulty getting the class properties to work on my own. That was because I did not recognize that the examples I found were implementing class properties in slightly different ways than what I was doing. I did not understand how the differences impacted how the class properties behaved. With that in mind, here are some important points I learned about creating class properties:

1. When the Getter and Setter Functions Are Required

In Example 1, the methods get_name and set_name are required. If you take out either method and try to set or retrieve a person's name, you will get an error:

AttributeError: can't set attribute

I point this out because there are many blogs which say that each of the default property functions are optional. While that is technically true, it is not very helpful advice when you are trying to learn how to use a class property to validate an input at the time an instance is created.

To back up a bit: python's property function contains four default attributes, as described in the python documentation for built-in functions:

class property(fget=None, fset=None, fdel=None, doc=None)

Return a property attribute.

fget is a function for getting an attribute value. fset is a function for setting an attribute value. fdel is a function for deleting an attribute value. And doc creates a docstring for the attribute.

https://docs.python.org/3/library/functions.html#property

There are times when you do not need to use any of the default attributes. For instance:

Example 2:

class Dog:

    def __init__(self, name):
        self.name = name

    @property
    def bark(self):
        print("Woof!")

Creating an instance of the Dog class and calling the bark property produces the following:

> d1 = Dog("Fido")
> d1.bark
Woof!

To use the bark property of the Dog class instance, there was no need to create a get_bark or set_bark function. However, in order to validate an input as in Example 1, you must create both a getter function and a setter function for the property. The reason is that instead of name simply pointing to an assigned value, it points to the property() function. Therefore, instead of p1.name retrieving the assigned value, it calls the property's getter function, which returns the value that has been assigned to _name. Similarly, p1.name = 'Tim' doesn't directly re-assign the name attribute. Instead, it calls the property's setter function, which assigns 'Tim' to _name. If either the getter or setter function is omitted from Example 1, the class's name property cannot be set or retrieved.

2. Be Mindful About How Variable Names Are Used

In Example 1, the variable name is used in the __init__ function and has the property function assigned to it. Within get_name and set_name, the variable _name is used. You can find many other examples of class properties that use two different variables, with the only difference between the variable names being a leading underscore in one of the variables. This is a naming convention used to indicate that the variable with the leading underscore is meant to be a "private" attribute. See a discussion regarding the use of underscores here: https://stackoverflow.com/questions/1301346/what-is-the-meaning-of-single-and-double-underscore-before-an-object-name

By having the variables name and _name identical aside from the underscore, it is easier to see that they are related. Although they are related, they must use different variables. You cannot use the same variable for both the property assignment and input assignment. If I change all the attribute values in Example 1 to 'name', it gets stuck in a loop:

RecursionError: maximum recursion depth exceeded while calling a Python object

That is because the self.name in the __init__ method calls the property() function which has been assigned to it. The property function then invokes either the get_name or set_name function. If either the get_name or set_name function uses self.name as the variable, it tries to call the property() function, which starts the loop over again. To avoid that issue, the variable used inside get_name and set_name must be distinct. It is convention to simply modify the property variable by adding an underscrore.

When learning about class properties, I was confused by many of the examples using the 'underscore' variable in the __init__ method. For instance, an example in the python documentation for built in functions uses _x as the variable in the __init__, getx, setx, and delx functions:

Example 3

class C:
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")

The reason it works to use _x in all the methods in Example 3 is that the value of _x is not being established at the time an instance of class C is created. Unlike the conditions for Example 1, where a person's name is provided when a Person instance is created, an instance of class C is created and, only after the instance exists, then x is assigned a value:

> c1 = C()
> c1.x
> c1.x = "value"
> c1.x
'value'

The variable _x is given a default value of None so that, before x is assigned a value, c1.x will return None rather than causing an AttributeError.

Example 1 would not work properly if the __init__ method used the _name variable. Instead of validating the name at the time an instance is created, it would only validate the name when the name is changed. A Person instance could be created with a name of the integer 1 (which violates the rule established in the set_name function), but its name could not then be changed to the integer 2 (because a name of 2 does not satisfy the rule in the set_name function):

ipdb> p2 = Person(1)
ipdb> p2.name
1
ipdb> p2.name = 2
ipdb> p2.name
1

But a Person class instance isn't supposed to be created in the first place if the name does not satisfy the rule in the setter function. So self._name cannot be used in Example 1's __init__ method. Instead, it must use self.name, which points to the set_name property function, so that the name provided at the time an instance is created can be validated.

Conclusion

There are many blogs and tutorials that explain how to create a class property, and they can be very helpful and informative. However, in order to get the most out of the advice they offer, it is important to be aware of how an example's use of the property function differs from how you may want to use it. The values that are provided when a class instance is created and whether those values can be changed make a difference in how the class property methods must be created, and even what default property attributes are required. Personally, once I understood the underlying reasons for variable names and property attributes, creating class properties became much easier.

The useState Hook and Forms in Controlled Components

Jim Grimes — Sun, 15 Oct 2023 20:51:36 +0000

Hello again! The past several weeks, my classmates and I have been learning how create websites using React. For this blog, I will be discussing an example of how to make forms in controlled components in React.

Creating Forms in Controlled Components

For the purpose of this discussion, I have made a simple app to list and view and search through the pizzas available at my favorite pizzeria:

function App() {
    const [pizzas, setPizzas] = useState([]);

    useEffect(() => {
        fetch("http://localhost:3001/pizzas")
        .then(resp => resp.json())
        .then(setPizzas)
    }, [])

    return (
        <div>
            <SearchBar />
            <AddPizza />
            <PizzaList pizzas={pizzas} />
        </div>
    );
}

This parent component, App, has three child components:

SearchBar, which contains a text input form used to search through the available pizzas,
AddPizza, which contains a form that can be used to add pizzas to the list of available pizzas, and
PizzaList, which displays the names and descriptions of the pizzas available at the pizzeria.

We are getting information about the available pizzas from a JSON database. The pizza information will need to be used by each of the child components of App, either to list the pizzas, add a new pizza, or search through the pizzas. Therefore, the useState hook is used to store the pizza information in App, the closest common ancestor of the three child components. The pizza information stored in state is passed as a prop to PizzaList, where the names and descriptions of pizzas are displayed.

The basic elements of AddPizza and SearchBar look like this:

function AddPizza({handleAddPizza}) {

    return (
        <form onSubmit={handleSubmit}>
            <input 
                type="text" 
                name="name" 
                placeholder="Enter Pizza Name" 
            />
            <input 
                type="text" 
                name="description" 
                placeholder="Enter Pizza Description" 
            />
            <input type="submit" value="Add Pizza" />
        </form>
    )
}

function SearchBar({handlePizzaSearch}) {

    return (
        <div>
            <input 
                type="text" 
                placeholder="Search Pizzas" 
            />
        </div>
    )
}

Both of these components contain text input fields. We need to plan out: (1) where we are going to store the text a user types into the forms and (2) where the event actions are going to be handled. In other words, we have to decide how to use state and props in a way that works best with our website.

In React, Controlled Components are those in which form’s data is handled by the component’s state. It takes its current value through props and makes changes through callbacks like onClick, onChange, etc. A parent component manages its own state and passes the new values as props to the controlled component.

https://www.geeksforgeeks.org/controlled-vs-uncontrolled-components-in-reactjs/

As the React documentation notes, we don't always have to make a component completely controlled or completely uncontrolled. We can customize how state and props are used based on our needs.

In practice, “controlled” and “uncontrolled” aren’t strict technical terms—each component usually has some mix of both local state and props. However, this is a useful way to talk about how components are designed and what capabilities they offer.

https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components

In this example, one of the forms will have state stored in the parent component and also receive a callback function as a prop, while the other form will use local state but still receive a callback function as a prop.

The Search Bar: Passing Props to Child Component with State in Parent Component

When a user types in the search bar, the list of pizzas will be filtered to find pizza names that match the user's input. The search does not wait for the user to hit a 'submit' button or any other action to trigger the search. It filters the list of pizzas as the user types.

We will store the user's input in state so that the state can be used to in our filter function. Because the text input in SearchBar must be used in real time to filter the list of pizzas, we should establish our state in App. Then, since our state is stored in App, we will filter the list of pizzas in App, and pass the filtered list to PizzaList to render the search results.

With that functionality added, the updated sections of App and SearchBar look like this:

function App() {
    const [pizzas, setPizzas] = useState([]);
    const [searchText, setSearchText] = useState("");

    <!-- useEffect omitted to keep example shorter -->

    function handleAddPizza(newPizza) {
        setPizzas([
        ...pizzas,
        newPizza
        ])
    }

    const filteredPizzas = pizzas.filter(pizza => pizza.name.toLowerCase().includes(searchText.toLowerCase()))

    return (
        <div>
        <SearchBar handlePizzaSearch={handlePizzaSearch} />
        <AddPizza handleAddPizza={handleAddPizza} />
        <PizzaList pizzas={filteredPizzas} />
        </div>
    );
}

function SearchBar({handlePizzaSearch}) {

    function handleSearchChange(event) {
        handlePizzaSearch(event.target.value)
    }

    return (
        <div>
            <input
                type="text"
                placeholder="Search Pizzas"
                onChange={handleSearchChange}
            />
        </div>
    )
}

The user's search input is stored in App as the searchText state. When the page loads, searchText is an empty string. As the user types, it is changed by setSearchText to whatever the user types into the search bar. The .filter() method is used to filter the list of pizzas, selecting only those pizzas with names that include the text typed into the search bar. To avoid requiring an exact match of capitalization, the filter changes both the pizza name and the search input to all lower case. Finally, instead of passing the original pizza state to the PizzaList component, the list of filtered pizzas is passed. If searchText is an empty string, like when the page first loads, every pizza name will be a match so every pizza will be included in the filtered list.

Adding a Pizza: A Mixture of Local State and Props

The next component, AddPizza, has a form with two text inputs and a submit button. The text inputs should be updated to reflect what the user types in, but we do not want to try to update or change the pizza database until the user hits the 'submit' button.

For this component, we can save its state locally, in AddPizza. We will create a function in App that will update the pizzas state when the new pizza is submitted. This function will be passed to AddPizza as a prop. When the user clicks the 'submit' button, the completed form data will be sent to the database in a POST request. In turn, the response from the JSON database will be an object containing the new pizza information plus a unique ID number. We can then pass that object to the callback function from App so that it can be added to pizzas in App. The updated, relevant sections of App and AddPizza are:

function App() {
    const [pizzas, setPizzas] = useState([]);

    <!-- state for searchText and useEffect omitted for brevity -->

    function handleAddPizza(newPizza) {
        setPizzas([
            ...pizzas,
            newPizza
        ])
    }

    <!-- functions for handlePizzaSearch and filteredPizzas omitted -->

    return (
        <div>
            <SearchBar handlePizzaSearch={handlePizzaSearch} />
            <AddPizza handleAddPizza={handleAddPizza} />
            <PizzaList pizzas={filteredPizzas} />
        </div>
    );
}

function AddPizza({handleAddPizza}) {
    const [formData, setFormData] = useState({
        name: "",
        description: ""
    })

    function handleFormChange(event) {
        setFormData({
            ...formData,
            [event.target.name]: event.target.value
        })
    }

    function handleSubmit(event) {
        event.preventDefault();
        fetch("http://localhost:3001/pizzas", {
            method: "POST",
            headers: {
                "Content-Type": "application/json"
            },
            body: JSON.stringify(formData)
        })
        .then(resp => resp.json())
        .then(newPizza => handleAddPizza(newPizza))
    }

    return (
        <form onSubmit={handleSubmit}>
            <input 
                type="text" 
                name="name" 
                placeholder="Enter Pizza Name" 
                value={formData.name} 
                onChange={handleFormChange} 
            />
            <input 
                type="text" 
                name="description" 
                placeholder="Enter Pizza Description" 
                value={formData.description} 
                onChange={handleFormChange} 
            />
            <input type="submit" value="Add Pizza" />
        </form>
    )
}

Both form text input fields begin with default values of empty strings. As the user types in the form, the name and value of the form field in which they type are used to update the section of formData that corresponds to the form field. The values in the formData object are used as the values shown in the form's text input so that the text the user sees matches the information stored in state. When a value in formData is an empty string, such as when the page first loads, the placeholder text is visible in the text input field.

After the new pizza is added to the database, we are using the response from JSON POST request to update the web page's list of pizzas, instead of using the information stored in state as formData. That is so the pizza added to pizzas will include a unique ID number which can be used as the key for the JSX list.

Finally, when we update pizzas in App to include the new pizza, we do so by making a copy of the current array stored in pizzas, not by simply adding the new pizza to the current array. By making a copy, React recognizes that we have changed the state and re-renders the page in order to reflect the new state.

Conclusion

Planning out how and where to use state is an important part of working with React components that include forms. Approaches similar to the ones outlined above can be used with toggle buttons, drop-down menus, and other features that require you to store input values in state and update the information on a page based changes to state. Thanks for reading!

Using Fetch Requests to Update a JSON Database Without Creating Duplicate Database Entries

Jim Grimes — Sun, 01 Oct 2023 20:31:44 +0000

Hello! In this blog, we will work through a process of checking whether information already exists in a JSON database and, if it doesn't, adding the information to the database.

Starting Conditions

As an example, we will use a JSON database containing basic information about pets. Each database entry includes the pet's name, age, and what kind of animal it is. When a user provides information about a pet, our task is to add the pet to the database. However, we do not want to create duplicate database entries, so we only want to add the user's input to the database if it does not already exist somewhere in the database. We start with the following database of pets:

{
"pets": [
    {
    "id": 1,
    "name": "Teddy",
    "animal": "dog",
    "age": 5
    },
    {
    "id": 2,
    "name": "Biscuit",
    "animal": "cat",
    "age": 8
    },
    {
    "id": 3,
    "name": "Bubbles",
    "animal": "goldfish",
    "age": 1
    }
]
}

The pet information from the user is provided in the following object:

let petInput = {
    name: "Scout",
    animal: "dog",
    age: "3"
}

Checking and Updating the Database

Retrieving Database Information

In order to compare the user's input with the objects that already exist in the database, we first need to obtain the current database information. We do this by using fetch() to send a GET request to the JSON database:

function getDatabaseInfo(petInput) {
    fetch('http://localhost:3000/pets')
    .then(response => response.json())
    .then(databaseInfo => databaseCheckFunction(databaseInfo, petInput))
}
getDatabaseInfo(petInput)

This function, getDatabaseInfo, is being used to start a chain of synchronous functions. Therefore, the user's input, petInput, is provided as an argument so that it can be passed as an argument as callback functions are invoked.

If you want to review the use of the fetch method and how to handle response received from the database, you can visit this site: https://javascript.info/fetch

Searching for Matching Database Entries

Now that we have an array of the current database objects, we can iterate through the array, searching for entries that match the user's input. For instance, we can use the find() method to search for objects with matching pet names:

function databaseCheckFunction(databaseInfo, petInput) {
    let searchedItem = databaseInfo.find(databaseEntry => {
        if (databaseEntry.name == petInput.name) {
            return true}
        })
    if (searchedItem == undefined) {
        addNewPetToDatabase(petInput)
    } else {
        console.log('This pet name already exists in the database')
    }
}

.find() will return the matching database entry if a match is found. If a matching entry is not found, it will return undefined. We want to add the new pet to the database only if a matching entry is not found, i.e. if .find() returns undefined.

For more information about using .find(), see the documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find

Adding New Pet to the Database

If no matching name was found in the database, the following function, addNewPetToDatabase, will be invoked. This function uses fetch() to send a POST request to add the new pet to database:

function addNewPetToDatabase(petInput) {
    fetch('http://localhost:3000/pets', {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        body: JSON.stringify(petInput)
    })
    .then(response => response.json())
    .then(newDatabaseEntry => console.log(newDatabaseEntry))
}

After the POST request, we can console log the response to confirm that the pet was successfully added to the database and see the database id number assigned to the pet.

Updating Existing Database Entries

In addition to adding a new pet to the database if a matching object value is not found, we can use the same method to update a database entry if a matching object is found. Instead of having our databaseCheckFunction console log a message if a matching pet name is found, we can pass the petInput object to a function that will use a PATCH or PUT request to update the database:

function databaseCheckFunction(databaseInfo, petInput) {
    let searchedItem = databaseInfo.find(databaseEntry => {
        if (databaseEntry.name == petInput.name) {
            return true}
        })
    // .find() will return the matching entry if a match is found.  Otherwise, it will return undefined.  We want to add the new pet to the database if a matching entry is not returned.
    if (searchedItem == undefined) {
        addNewPetToDatabase(petInput)
    } else {
        updatePetInDatabase(petInput)
    }
}

In this example, we will use a PUT request to overwrite an existing database entry with the petInput information:

function updatePetInDatabase(foundItem, petInput) {
    fetch('http://localhost:3000/pets/'+foundItem.id, {
        method: "PUT",
        headers: {
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        body: JSON.stringify(petInput)
    })
    .then(response => response.json())
    .then(updatedDatabaseEntry => console.log(updatedDatabaseEntry))
}

The following blog discusses the difference between PATCH and PUT requests: https://medium.com/@9cv9official/what-are-get-post-put-patch-delete-a-walkthrough-with-javascripts-fetch-api-17be31755d28

Conclusion

If we are unsure whether information already exists in a database, we retrieve the database with fetch using a GET request and then iterate through the response, searching for matching information. In this example, we searched for a matching name using the .find() method, but other methods can be used. For instance, if we need to anticipate finding several instances of matching database entries, we could use the .filter() method. If no match is found, the new information can be added to the database with a POST request. Alternatively, an existing database entry can be altered by using a PATCH or PUT request.

I have found the above-outlined steps to be useful in completing multiple tasks assigned to me as a software engineering student, and I hope they can be useful to you as well. Thanks for reading!