DEV Community: Jesse Smith Byers

AI Scoring Agent: Lessons Learned and New Directions

Jesse Smith Byers — Thu, 23 Oct 2025 12:03:35 +0000

In my previous posts in the series, I described an AI Scoring Agent prototype that was designed to score open-ended student responses using a scoring guide. While the agent performed well in some cases, my last post outlined a number of ways in which it fell short. This final post is written more from my educator perspective, and shares my lessons learned about AI in student assessment. Although this has shown that AI agents should NOT score student assessments, I also share some new directions in which this type of tool could be appropriate and helpful.

Lessons Learned about AI in Assessment

1. AI Agents SHOULD NOT Score Student Responses

This was highlighted in my last post, so I will not repeat the evidence here. I am admittedly an AI skeptic in regards to education, so this lesson is not at all surprising to me. Hallucinations generated by the LLM are the biggest concern, so any further work in using LLM-based agents for assessment would have to solve this problem first.

2. But...AI Agents CAN Replicate The Human Scoring Process

A positive finding was that agents can be designed to replicate the structured scoring processes that are required to score open-ended responses. I was able to have the agent internalize the scoring guide by summarizing the differences between each score level and coming up with a solid plan to apply the scoring criteria to the response.

Additionally, an agent can verify scores, and use conditional logic to determine whether fact checking, or re-planning is necessary. This agent was designed to save its scoring plan as long as it was producing scores that could be verified, but also was able to replace plans that were not working well with new plans, which also reflects a human process of trying new approaches if an old approach stops being effective.

3. Examples and Strict Formats Are Not Always Helpful

In human scoring, teachers are trained using a scoring guide and a collection of exemplars (multiple examples of student responses at each score level, with a score and an explanation). These exemplars are designed to help each teacher calibrate on what each score level looks like, so that groups of teachers will score similar to each other. Examples are contained within the STAAR materials that I used in this project.

In the first version of the agent, I provided 3 few-shot examples of student responses and example explanations at each score level for the agent to train on, with the hope that it would calibrate similar to how humans calibrate on these examples. I quickly learned that these examples limited the agent's ability to accurately score new responses - if the new response was not similar to a training response, then it would receive a low score, even if the response was correct.

In the same vein, my attempts to provide more specific guidance in terms of formatting the agent's scoring plan, or structuring the explanations for each score also led to poorer results. In both cases, it seemed that the agent overtrained on the examples, to the detriment of its performance on new student responses.

4. The Agent Knows Enough Without Fact Checking

While tools can be helpful, adding tools can lead to unneeded complexity without additional benefits. In the case of my agent, none of the content required up-to-the-minute accuracy, so the LLM's training material had already contained the factual information needed to score any of the science questions. The fact checking just increased runtime without real benefit.

5. The Agent Generally Shares Reasonable Text Explanations

In most cases, the explanations matched evidence in the student response and reflected criteria in the scoring guide, and this was more reliable than the numeric scores the agent might produce. This opens the door towards using agents for more formative, feedback-oriented tasks than grading tasks. In fact, unprompted, the agent often would suggest specific improvements to a student response to elevate it to the next score level!

New Directions

As I stated at the outset, I am an AI in education skeptic. Although this exploration confirmed my belief that AI agents should not be used for scoring, this exercise has highlighted some new directions in which similar AI agent-based tools could be useful for teachers or students.

1. Coaching Students to Write Explanations

Many students struggle with writing in science class, specifically when asked to develop explanations in Claim-Evidence-Reasoning (CER) format. There are many rubrics focused on scoring CER explanations. The tool could be used by a student to evaluate their CER response against a CER rubric, and the score and explanation could give them valuable feedback on how to better structure their answer. This process could be fairly self-directed by a student, before handing in an answer to be graded by a (human) teacher.

For example, the agent used the CER Rubric below to grade a question about photosynthesis.

CER Rubric:

Question:

Student Response:

“Blue light resulted in more bubbles than red or green so it had the highest rate. I know green light is often reflected by plants so less is used, so the plant did less under green, and red was lowest.”

The tool (with unaltered prompts) returned the following final score and explanation:

SCORE: 2
EXPLANATION: The student's response includes a claim that blue light had the highest rate based on observed bubbles, provides some evidence related to plant pigmentation, and gives reasoning connecting green light reflection with lower photosynthesis. However, the claim is not directly supported by evidence from the table provided in the plan, and the explanation does not fully explain the impact of specific wavelengths on photosynthesis or connect it accurately to the data mentioned. The response lacks precision due to vague references ("more bubbles") and does not completely align with a coherent scientific argument structure (Claim-Evidence-Reasoning).

A student reading this could infer that the response would be stronger if they:

used evidence from the data table
expand the answer to include details about wavelength and impact on photosynthesis
used more precise language
explicitly identified their claim, evidence, and reasoning within the answer

The student could polish up their answer, feed it through the AI agent for additional feedback, and submit it to the teacher when they have achieved a higher score. With only a small adjustment to the text prompt within the score node, the agent could provide the feedback in a more explicit manner.

2. Providing a Second Opinion For A Human Scorer

Teachers are always exhausted, and grading open-ended responses takes a long time. Much of this time is spent debating internally whether a response is closer to one score level description or another. While it is ideal to get a second set of eyes on a student response, that is not always feasible. Instead, a teacher could use the scoring agent for individual responses that they consider to be borderline, and consider the agent's score and explanation as a second opinion to help them justify a higher or lower score. This would not replace the human grading in any way, but would just add additional perspective.

3. Make Exit Tickets More Productive

Exit tickets are considered a best practice in teaching. A teacher gives the class a carefully-constructed question at the end of class that is handed in before the bell. Ideally, the teacher reads all of the responses overnight (but does not grade them), does some analysis of trends within the answers, and uses this data to plan the next day's instruction. However, the exit ticket strategy often falls apart because it is time-consuming to carefully examine all of the responses, and many teachers don't have time to analyze the data on a daily basis.

This scoring tool could be adapted to accept a batch of student exit ticket answers, and return an analysis at the class level. It could highlight trends in the class by summarizing the explanations returned when each exit ticket response is scored. This way, a teacher can collect general information about where the class stands, and use that information to plan a lesson around any student misconceptions or partial understandings that are uncovered. Individual students would never be held accountable to a score assigned by a machine, but everyone would benefit from the insights delivered by the scoring agent.

Wrapping Up

My experience of designing and building a prototype AI Scoring Agent has been illuminating. While it confirmed my suspicions that grading needs to be done by a human, it did spark some ideas for how AI agents could be designed to reduce the burden on teachers, allowing them to focus their limited time on tasks that are most important for their students.

A lot of AI-focused work is being done right now in education, and my hope is that those working in the EdTech sector continue to have a healthy curiosity to explore what's possible, throw out ideas that don't work, and use the experience to spark new ideas that can benefit both students and teachers.

AI Scoring Agent Behavior: The Good, The Bad, and The Ugly

Jesse Smith Byers — Wed, 22 Oct 2025 14:08:49 +0000

In the first post of this series, Building an AI Scoring Agent: Step-By-Step, I described the technical details of building an AI Scoring Agent for scoring open-ended science questions. This post analyzes the behavior of the prototype tool, and reflects on appropriate and inappropriate use cases for a tools like this.

TLDR: This shouldn't be used for scoring tests or exams!!!

As a recap, the tool takes in a scoring guide, a question, and a student response, and outputs a score and an explanation for the score. The sections below analyze the behavior of the agent when it is working as expected, as well as analyzes its workflow and output when things go awry.

The Good

The Agent Follows Simple Workflows

In many cases, the agent works as expected, following a predictable workflow as described in the code and summarized in the first post. The first post ended with an output example of the simplest workflow, of Plan -> Score -> Verify, outputting an accurate answer that matches the "ground truth" of a human scorer. Notably, the scoring plan is reasonable based on the scoring guide, and the explanation generated is consistent with the student response and the scoring guide.

The Agent Can Optionally Fact Check

Similarly, there were many cases in which the agent followed a more complicated path, sometimes integrating the web search tool, and re-scoring to get to an accurate score that matches the "ground truth" of a human scorer.

For example, the output below is from scoring a student response of "sodium-2, sulfur-1, oxygen-4", which is a correct response that should earn a score of 2. The agent used fact checking to check how many atoms are in the chemical formula, then scored the answer correctly.

================== A. PLANNING SCORING APPROACH ==================
🧠 Generating new plan

...(plan removed for brevity)...

================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: Fact check triggered with query: number of atoms in sodium, sulfur, and oxygen

================== B. FACT CHECKING (Optional) ==================
Fact check QUERY → RESULT: number of atoms in sodium, sulfur, and oxygen → Jan 5, 2022 · So, it's 2 atoms of Sodium , 1 atom of Sulfur , and 4 atoms of Oxygen , which gives us a total of 7 atoms per molecule of Na2SO4. The 'Total # of atoms ' refers to the total count of ato...
Score after fact check: Score: 2
EXPLANATION: The student provides a complete and accurate response by listing the total number of atoms (7) across three distinct elements (sodium, sulfur, and oxygen). Sodium is correctly identified as contributing two atoms, sulfur as one atom, and oxygen as four atoms.

================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: SCORE: 2
EXPLANATION: The response correctly identifies all elements and their respective atom counts. Sodium is listed as contributing two atoms, sulfur as one atom, and oxygen as four atoms, resulting in a total of seven atoms per molecule of Na2SO4.

==================== D. VERIFYING SCORE ====================
Verification response: {
    "new_score": 2,
    "reason": "The student response correctly identifies the total number of atoms and elements, although it uses a different notation (sodium-2 instead of Na2)."
}
OLD_SCORE: 2  -  NEW_SCORE: 2

******************** FINAL ANSWER *******************
SCORE: 2
EXPLANATION: The response correctly identifies all elements and their respective atom counts. Sodium is listed as contributing two atoms, sulfur as one atom, and oxygen as four atoms, resulting in a total of seven atoms per molecule of Na2SO4.

The Agent Can Revise The Plan To Produce Correct Scores

In the example below, the agent follows a more complex path: Plan -> Score -> Verify -> Re-Plan -> Re-Score -> Fact Check -> Re-Score -> Re-Verify. In the end, it verifies the accurate score of 1.

================== A. PLANNING SCORING APPROACH ==================
🧠 Generating new plan

...(plan removed for brevity)...

================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: SCORE: 1
EXPLANATION: The response acknowledges an external force (the hand's push), but lacks detail on other critical forces like gravity, friction, and the normal force. It also does not explain how these forces affect the block's motion before release or after being released from the hand's influence.

==================== D. VERIFYING SCORE ====================
Verification response: {
    "new_score": 2,
    "reason": "The student response demonstrates an understanding of force and motion, relating the action of pushing to the movement of an object. However, it lacks clarity in describing the relationship between direction and distance."
}
OLD_SCORE: 1  -  NEW_SCORE: 2

================== A. PLANNING SCORING APPROACH ==================
🧠 Generating new plan

...(plan removed for brevity)...

================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: Fact check triggered with query: Is pushing a box considered as applying force downwards due to gravity?

================== B. FACT CHECKING (Optional) ==================
Fact check QUERY → RESULT: Is pushing a box considered as applying force downwards due to gravity? → In straight and level flight, lift equals weight. In a steady level banked turn of 60°, lift equals double the weight. The pilot experiences 2 g and a doubled weight. The steeper the bank, the greater...
Score after fact check: SCORE: 1
EXPLANATION: The student's response only mentions a single force (the force of the hand), which is not enough to understand the complete dynamics of motion in such scenarios. They do not include gravity, normal force, or friction as forces acting on the block. No description is provided for how these forces affect the box before or after it is pushed.

================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: SCORE: 1
EXPLANATION: The student's response does not mention gravity, friction, or normal force. It also fails to explain how any forces are affecting the motion of the box before and after it is pushed.

==================== D. VERIFYING SCORE ====================
Verification response: {"new_score": 1, "reason": "The student response demonstrates a basic understanding of force and motion, using correct vocabulary."}
OLD_SCORE: 1  -  NEW_SCORE: 1

******************** FINAL ANSWER *******************
SCORE: 1
EXPLANATION: The student's response does not mention gravity, friction, or normal force. It also fails to explain how any forces are affecting the motion of the box before and after it is pushed.

Summary of the Strengths

In summary, the agent can follow its workflow to (at times) produce accurate scores, either taking a simple path (Plan -> Score -> Verify) or through taking more complicated paths including optional fact checking, and re-planning, re-scoring, and re-verification. However, the agent does not produce correct answers all the time, as illustrated in "The Bad" and "The Ugly" sections below.

The Bad

The Fact Check Can Lead To Inaccurate Scores, and Might Be Unnecessary

In this example, the agent calls the fact check, even though it already has the facts it needs clearly identified in its scoring plan. Furthermore, it seems to give the response all of the points based on the results of the fact check, and not the content of the student response. The student response for this run was "Na, S, O", which should receive a score of 1 because it does not include atom counts.

================== A. PLANNING SCORING APPROACH ==================
✅ Using cached plan

...(plan edited for brevity)...

**Flowchart Plan:**
- **Step 1:** Identify if the student answers both parts of the question correctly (elements and atoms).
    - **IF** Student answers that there are sodium, sulfur, and oxygen elements AND
        - **THEN** Check if student mentions correct atom counts for each element.
            - **IF** Correct atom counts identified (2 sodium, 1 sulfur, 4 oxygen) 
                - **THEN** Assign Score 2

...(plan edited for brevity)...


================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: Fact check triggered with query: formula for sodium sulfate

================== B. FACT CHECKING (Optional) ==================
Fact check QUERY → RESULT: formula for sodium sulfate → Sodium sulfate is an inorganic compound with formula Na2SO4 and several related hydrates. It is a white solid that is highly soluble in water and has various applications in industry and medicine. Jul...
Score after fact check: SCORE: 2
EXPLANATION: The student correctly identified all elements (sodium, sulfur, oxygen) but did not specify their respective atoms in the sodium sulfate formula. A perfect response would include both the correct identification of elements and their atom counts (Na, S, O). In this case, since only the elemental symbols were provided without detailing the number of atoms for each element, the score is 2.

...(output edited for brevity)...

******************** FINAL ANSWER *******************
SCORE: 2
EXPLANATION: The student correctly identified all elements (sodium, sulfur, oxygen) and provided their respective atoms in the sodium sulfate formula.

The Agent Struggles With Partially Correct Student Responses

The example above also illustrates how the agent struggles more with student responses that should receive partial credit than responses that are clearly correct or clearly incorrect. However, this may be explained by the quality of the scoring guide. The Texas STAAR scoring guides tend to give a lot of detail for a score a 2, and much more vague descriptions for scores of 1 or 0, as shown below:

Score 2: The student response includes:
- There are a total of 7 atoms representing three elements in the formula
- AND
- The elements are sodium (2 atoms), sulfur (1 atom), and oxygen (4 atoms).
Score 1: The student answers half of the question correctly.
Score 0: The response is incorrect or irrelevant.

Summary of the Weaknesses

Initial tests showed that while the fact checking functionality worked as it was directed, it did not help the agent to increase accuracy in scoring, and may result in more inaccurate scores. In addition, the agent performs better on responses that are correct and should earn the highest score possible, and struggles more on the partially correct student responses.

The Ugly

The LLM Hallucinates While Making Plans and Composing Explanations

While the agent was successful at times, hallucinations were a major problem. For example, when making scoring plans, the agent usually created reasonable plans that matched the scoring guide, but at times would create plans that introduced additional score levels that didn't exist in the scoring guide, or made up processes to add or deduct points that were not consistent with the scoring guide.

In this forces and motion example, the plan includes too many score levels and makes up a process for point deductions, and as a result produces inaccurate scores. The original scoring guide has only 0-2 points, not 3.

...(response shortened for brevity)...

7. **Summarize Final Score**: Award total points based on cumulative score from each section.
   - APPLY scoring guide rules: 3 points if all forces are identified with accurate explanations; decrease points accordingly for less comprehensive or inaccurate responses.

**Note:** This plan assumes a simplified point system where points can be lost but not awarded, maintaining the grading scale's integrity. Adjustments may vary based on specific grading criteria outlined in `scoring_guide_2`.

This flaws in this plan were probably generated by simple text prediction, based on other scoring guides that Ollama had access to during LLM's original training. The verification node, which could trigger re-planning, helped to mitigate this problem, but the problem still exists and came up more frequently with scoring guides that were less detailed.

In addition, hallucinations were detected in score explanations, noting details about student responses that were not actually present in the response itself. For example, in this case, the student response only includes the elements, "Na, S, O" and should receive a score of 1.

SCORE: 2
EXPLANATION: The student correctly identified all elements (sodium, sulfur, oxygen) and provided their respective atoms in the sodium sulfate formula.

Again, these hallucinations are likely an artifact of text prediction more than anything else.

Text in the Student Response Can Influence Scoring

Finally, text in the student response can override the agent's prompt, leading to score the response as directed by the student. This is obviously a major problem that would prevent LLM-based agents from being used for exam-based scoring, as pointed out by a commenter on my first post:

Summary

As described above, while the agent can provide some accurate scores and reasonable explanations, it has some major limitations and flaws that would prevent it from being used for scoring summative student assessments, such as exam responses.

In my final post, I'll share some reflections I have about some possible use cases of agent-based scoring given these limitations, and some lessons learned (both tech and education-focused) from the process of building this prototype.

Building an AI Scoring Agent: Step-By-Step

Jesse Smith Byers — Tue, 21 Oct 2025 18:48:07 +0000

As a former teacher and curriculum developer, I've been curious about the potential of AI in scoring open-ended student responses. In this post, I'll walk you through my prototype design of an AI scoring agent, explain the code, and explore its initial outputs. In a follow-up post, I'll evaluate it's performance using multiple inputs, and reflect on what we can learn from how the agent approaches scoring tasks.

All of the code and example outputs described in this article can be found in the GitHub repository.

The Prototype Design

When I started designing my scoring agent, I wanted it to be able to do the following:

Score student responses to questions based on a provided scoring guide
Provide a score and an explanation describing why it assigned the score
Be able to look up facts on the web (if needed)
Have some mechanism for quality control, by double-checking its work

After some exploration of multiple options, I decided to implement the AI Scoring Agent using the following tools:

The prototype agent was built in the form of a Jupyter notebook for easy and lightweight experimentation
LangChain was used to create the agent with Ollama chat and DuckDuckGo web search tool
LangGraph was used to construct the Graph and direct the agent's workflow
NetworkX and Matplotlib were used to visualize the graph structure of the agent

AI Agent Workflow: The Big Picture

The agent takes in three string inputs at the start: a question, a student response, and a scoring guide.

In the planning node, it reads the question and the scoring guide, and creates a plan that it will follow to score a student response for that question.
It then moves to the scoring node, and attempts to follow it's plan to score the response.
- If it can score the response without any additional information, it scores it and moves to the verification node.
- If it needs to fact check anything, it can conduct a web search before scoring the response.
After scoring, it passes the score and explanation to the verification node, where it checks it's work.
- If the score is verified, the score and explanation are passed to the user as the final answer.
- If the score is not verified, the agent goes back to the planning node to make a new plan, rescore, and re-verify.

The Code

Follow along in the Jupyter notebook to explore the code and outputs discussed below.

Environment Setup, Installations, and Imports

I used a Jupyter notebook within a virtual environment in VSCode to work on this project. I installed all required packages in the virtual environment, including the following:

pip install langchain langchain-core langchain-community langgraph langchain-ollama networkx

The project requires the following imports:

# for creating the state and graph workflow
from langgraph.graph import StateGraph, END

# for integrating the LLM
from langchain_ollama import ChatOllama

# for integrating web search
from langchain_core.tools import tool
from langchain_community.tools import DuckDuckGoSearchRun

# for visualizing the graph
import networkx as nx
import matplotlib.pyplot as plt

# general tools
from typing import TypedDict, Optional
import json
import os
import re

Utility Functions

The next cell in the notebook organizes the utility functions that will be called. Look at the Jupyter notebook to see the code.

The first two are used to cache the agent's plans so they can be re-used in future scoring tasks using the same question and scoring guide, which makes the agent more efficient and consistent across runs.

The extract_score_from_output function is used to pull a numeric score out of the agent's output to be used for verification.

Building the Agent

The next cell includes all of the logic to build the agent, hook it up to the LLM, and give it tools, prompts, and a clear workflow. I'll describe each chunk of code step-by-step.

Setting up the Agent and Tools

class AgentState(TypedDict):
    question: str
    student_response: str
    scoring_guide: str
    plan: str
    score: Optional[int]
    output: Optional[str]
    retry_count: 0
    fact_query: Optional[str]
    fact_verified: Optional[str]

First, define the AgentState class. This is a typed dictionary that establishes the structure of the state that will be passed to each node as the agent performs its work. In this case, the question, student_response, and scoring_guide are required, and must be provided as input to the agent. The plan is required, and is generated in the planning node. The score and output are generated by the LLM in the scoring node, and are optional. In fact, the presence or absence of these keys is used to conditionally direct the agent to its next step. Similarly, the retry_count, fact_query, and fact_verified keys are also used to conditionally direct the agent. This will be explained as we build the nodes in the next section.

# Initialize the LLM using Ollama qwen2:7b
llm = ChatOllama(model="qwen2:7b")

This scoring agent is built upon an already-existing large language model, which allows it to interact with natural text prompts and compose its responses. I used an Ollama LLM because it was free, did not require an access key, and could be run locally.

# Set up web search tool for fact checking
@tool
def fact_check(query: str) -> str:
    """Search the web to verify science facts."""
    search = DuckDuckGoSearchRun()
    return search.run(query)

tools = [fact_check]

Autonomous agents generally have access to a number of different tools that they can optionally call as needed. In this case, the agent only has access to one tool, a web search tool. I chose the DuckDuckGo tool because it was also free and did not require any access keys.

Building the Nodes

In its current state, the scoring agent has 4 nodes:
A. Plan Node
B. Fact Check Node (Optional)
C. Score Node
D. Verify Score Node

Each node has a similar structure. Each node is set up as a function, which takes in the StateGraph as an argument, and can be called to execute the work of that node. Each node has the following components:

a description of what it does (as well as and conditions)
a textual prompt telling the LLM what to do
a call to the LLM using the prompt, which generates a response
logic on how to handle the response, including updating the StateGraph

The nodes themselves are fairly independent from one another. The logic for moving from one node to another in a workflow is generally defined in the graph structure, described in a later section.

A. Plan Node

The planing node is one of the simpler nodes: It checks if there is already a cached plan, and returns it. If there is not an existing plan, it sends a prompt to the LLM requesting it to generate a plan based on the scoring guide.

# Planning node
def plan_scoring_approach(state: AgentState):
    """
    Checks if there is already a scoring plan in the cache.
    If yes, reuses the existing plan.
    If no, generates and caches a new plan.
    """
    print("\n================== A. PLANNING SCORING APPROACH ==================")
    cache = load_plan_cache()

    # check if current question / scoring guide already in cache
    key = f"{state['question']}|{state['scoring_guide']}"

    if key in cache:
        print("✅ Using cached plan")
        plan = cache[key]
        print(plan)

    else:
        print("🧠 Generating new plan")

        prompt = (
            "You are an expert scoring assistant who creates structured scoring plans for student responses.\n\n"
            "Your goal is to analyze the question and scoring guide, summarize the key distinctions between scores, "
            "and then write a clear, step-by-step flowchart plan for assigning a score.\n\n"
            "### Instructions for this task:\n"
            "1. Read the new question and scoring guide carefully.\n"
            "2. Summarize the main distinctions between each score level.\n"
            "3. Write a new flowchart plan, following the example format above (use bullet points and IF/THEN structure).\n\n"
            f"### Question:\n{state['question']}\n\n"
            f"### Scoring Guide:\n{state['scoring_guide']}\n\n"
            "### Output Format:\n"
            "**Summary:** <summary of score distinctions>\n\n"
            "**Flowchart Plan:** <new step-by-step plan>\n\n"
            "Return only the summary and flowchart plan — no commentary or self-reflection."
        )

        response = llm.invoke(prompt)
        plan = response.content
        cache[key] = plan
        save_plan_cache(cache)
        print(plan)

    return {"plan": plan}

One of the key things to note in this function is the prompt itself. Note how you can use a formatted string (f"text {variable} text") to make sure the LLM is considering the correct resources from the state, such as {state['question'] and {state['scoring_guide']}. Markdown can be used to format, organize, and add emphasis to the prompt as well.

B. Fact Check Node (Optional)

The purpose of the fact checking node is to send a query to the LLM and receive web search results back. It can then attempt to score the student response using the additional information from the web search. This is optional, and the agent will decide if it is needed during each task.

# Fact checking node (as needed)
def fact_check_node(state: AgentState):
    """
    Send a query to DuckDuckGo and receive web search results.
    """
    print("\n================== B. FACT CHECKING (Optional) ==================")
    query = state.get("fact_query", "")
    if not query:
        return {"output": "No query provided for fact-checking."}

    result = fact_check.invoke({"query": query})
    print(f"Fact check QUERY → RESULT: {query} → {result[:200]}...")

    # Immediately rescore using verified info
    prompt = (
        "SYSTEM: You now have verified scientific information. "
        "Use it to rescore the student response without calling any tools.\n\n"
        f"FACTS:\n{result}\n\n"
        f"PLAN:\n{state['plan']}\n\n"
        f"STUDENT RESPONSE:\n{state['student_response']}\n\n"
        "Your output must include:\n"
        "SCORE: <integer>\n"
        "EXPLANATION: <why this score>\n"
        "Return ONLY the explanation and score."
    )

    response = llm.invoke(prompt)
    print(f"Score after fact check: {response.content.strip()}")

    # Return directly to verification with updated output
    if response.content:
        return {
            "fact_query": None,
            "fact_verified": result,
            "output": response.content.strip(),
            "score": extract_score_from_output(response.content)
        }
    else:
        return {"output": None}

C. Score Node

The scoring node is a bit more complex than the other nodes because it brings in more conditional logic. I experimented with multiple approaches in regards to HOW and WHERE to include conditional logic. For example, conditional logic could be written into the textual prompt in plain English, it could be written in code outside of the prompt using if...elif...else and comparison operators to define the conditions, or it could be handled in the graph structure itself, by creating additional smaller nodes to handle every condition and define routing across those nodes. There are pros and cons to each approach.

In its current state, this agent includes some code-based conditional logic, as it seemed more successful than text-based logic. This logic determines whether the agent will execute a web search to collect additional science facts to help score the response. This approach uses some of the optional keys in the state as flags to determine which action to take.

# Scoring node
def score_student_response(state: AgentState):
    """
    Generate a score and explanation for the student response.
    Optionally calls fact_check once; if fact is already verified, rescores only.
    """
    print("\n================== C. SCORING STUDENT RESPONSE ==================")

    # Build prompt
    prompt = (
        "SYSTEM: You are an assistant that scores student responses.\n"
        "Follow the provided plan carefully.\n\n"
    )

    if state.get("fact_verified"): # already called fact check once
        prompt += (
            "SYSTEM: Verified factual information is already available.\n"
            "Do NOT call any tool again.\n"
            "Use ONLY the verified facts below when scoring.\n\n"
            f"VERIFIED FACTS:\n{state['fact_verified']}\n\n"
        )
    else: # has not called fact check, may call fact check once
        prompt += (
            "If uncertain about a scientific fact, you MAY call the `fact_check` tool **once**.\n"
            "Only verify objective facts relevant to the question.\n"
            "Do NOT include student opinions or reasoning in your query.\n\n"
        )

    prompt += (
        f"PLAN:\n{state['plan']}\n\n"
        f"STUDENT RESPONSE:\n{state['student_response']}\n\n"
        "Output format:\n"
        "SCORE: <integer>\n"
        "EXPLANATION: <why this score>\n"
        "Return ONLY these two lines.\n"
    )

    # Call LLM 
    response = llm.bind_tools(tools).invoke(prompt)

    # Handle response
    if response.content and not response.tool_calls:
        score = extract_score_from_output(response.content)
        print(f"Scoring Output: {response.content}")
        return {
            "output": response.content.strip(),
            "score": score
        }

    # Handle tool call (fact check)
    if response.tool_calls:
        tool_call = response.tool_calls[0]
        if tool_call["name"] == "fact_check" and not state.get("fact_verified"):
            print(f"Scoring Output: Fact check triggered with query: {tool_call['args']['query']}")
            return {
                "fact_query": tool_call["args"]["query"],
                "output": None,
                "score": None
            }

    # Error handling
    print("Scoring Output: No valid output from scoring node.")
    return {"output": None, "score": None}

D. Verify Score Node

The final node is responsible for re-scoring the student response using the scoring guide, comparing the two scores it has generated for the response, and either verifying the score and returning it, or cycling back to create a new scoring plan and try again. The conditional logic within this node primarily focuses on limiting the re-planning and re-scoring to two total retries, in order to avoid getting stuck in an infinite loop without a clear score.

def verify_score_node(state: AgentState):
    """
    Re-scores the student response and compares to old score.
    If the scores do not match, reverts to plan node to make new plan and new score (up to 2 times).
    """
    print("\n==================== D. VERIFYING SCORE ====================")

    # If no score yet, generate it first at score node
    if "score" not in state or state["score"] is None:
        print("No score yet, generating one...")
        score_result = score_student_response(state)
        state.update(score_result)

    # Prompt the model to independently score the student response based only on the guide
    prompt = f"""
        You are a scoring assistant. Ignore any previous scores or plans. 

        Your task:
        1. Independently read the student response below.
        2. Assign a new score strictly according to the SCORING GUIDE provided.
        - Do NOT consider the previously assigned score in choosing the new score.
        - Ensure the score does not exceed the maximum points described in the guide.
        3. Return only a JSON object.

        SCORING GUIDE:
        {state['scoring_guide']}

        STUDENT RESPONSE:
        {state['student_response']}

        Output:
        Return ONLY a single JSON object with this format:
        {{
            "new_score": <integer>,
            "reason": "<brief explanation why this score is appropriate>"
        }}

        Example output format (numbers are placeholders):
        {{"new_score": <score>, "reason": "The student meets all criteria for this score."}}
    """

    response = llm.invoke(prompt)
    print(f"Verification response: {response.content}")

    try:
        verification_result = json.loads(response.content)
        new_score = verification_result.get("new_score")
        reason = verification_result.get("reason", "")
    except Exception as e:
        print("Failed to parse verification JSON:", e)
        # If parsing fails, assume the score is verified to prevent infinite loops
        print("\n******************** FINAL ANSWER *******************")
        state["output"] += "\nCONFIDENCE: Low (Unverified Score)"  # low confidence because verification failed
        return {"output": state.get("output")}

    # Compare the new score to the original
    old_score = state.get("score")
    print(f"OLD_SCORE: {state.get("score")}  -  NEW_SCORE: {new_score}")

    try:
        if int(new_score) == int(old_score):
            verified = True
        else:
            verified = False
    except:
        verified = False

    if verified: 
        # Accept score 
        print(f"\n******************** FINAL ANSWER *******************")
        return {"output": state.get("output"), "verified": verified, "reason": reason}
    elif state.get("retry_count", 0) >= 1:
        # append confidence low
        state["output"] += "\nCONFIDENCE: Low"
        print(f"\n******************** FINAL ANSWER *******************")
        return {"output": state.get("output"), "verified": verified, "reason": reason}
    else:
        # Increment retry count
        state["retry_count"] = state.get("retry_count", 0) + 1
        # Score not verified → clear plan and output to trigger a new plan
        state["plan"] = None
        state["output"] = None
        # Delete the old plan from cache
        cache = load_plan_cache()
        key = f"{state['question']}|{state['scoring_guide']}"
        if key in cache:
            del cache[key]
            save_plan_cache(cache)
        return state

Building the Graph Structure

As noted above, the nodes are fairly independent of one another, and the workflow is instead directed by a graph structure with edges connecting the nodes. The code below shows how conditional logic is used to direct the workflow along certain edges, depending on the contents of the StateGraph.

# Build the graph
graph = StateGraph(AgentState)
# add nodes
graph.add_node("plan_node", plan_scoring_approach)
graph.add_node("score_node", score_student_response)
graph.add_node("verify_score_node", verify_score_node)
graph.add_node("fact_check_node", fact_check_node)
# set entry point
graph.set_entry_point("plan_node")
# add edges
graph.add_edge("plan_node", "score_node")
graph.add_edge("fact_check_node", "score_node")
graph.add_edge("verify_score_node", END)

# --- CONDITIONAL EDGES ---
# From SCORE node
def route_from_score(state: AgentState):
    """
    Conditional routing after scoring:
    - If a fact check is needed → go to fact_check_node
    - If a score was produced → go to verify_score_node
    - If facts were verified but output missing → go re-score
    - Otherwise → end
    """
    if state.get("fact_query"):
        return "fact_check_node"
    elif state.get("fact_verified") and not state.get("output"):
        return "score_node"  # re-score after facts retrieved
    elif state.get("output"):
        return "verify_score_node"
    else:
        return END

graph.add_conditional_edges(
    "score_node",
    route_from_score,
    {
        "fact_check_node": "fact_check_node",
        "verify_score_node": "verify_score_node",
        "score_node": "score_node",  # needed for re-scoring after fact check
        END: END,
    }
)

# From VERIFY node
def route_from_verify(state: AgentState):
    # If not verified and plan was cleared → regenerate plan (retry up to 2 times)
    if state.get("plan") is None and state.get("retry_count", 0) <=1:
        return "plan_node"
        # If verified successfully → end
    elif state.get("output"):
        return END
    # Otherwise → stop after 2 retries
    else:
        return END

graph.add_conditional_edges(
    "verify_score_node",
    route_from_verify,
    {"plan_node": "plan_node", END: END}
)

# Compile the graph
app = graph.compile()

Visualizing the Graph

The next cell in the notebook includes code for visualizing the graph, and will not be discussed here.

As a recap: The question, student response, and scoring guide are passed to the planning node, which generates a scoring plan based on the scoring guide. In the scoring node, the response is scored, and the score and explanation are sent to the verification node to verify the score and return it as the final output.

If a web search is needed to collect factual information, the agent can conduct only one web search through the fact check node, and then return to score the response.

If the original score cannot be verified, then the against deletes the original scoring plan and returns to the planning node to create a new (and ideally better) plan. It then continues through the scoring and verification. There is a limit of only two retries, and the final answer is appended with a message that the confidence is low if the agent was unable to verify the score after the maximum allowed retries.

Initial Performance Demo

As you probably noticed in the code snippets, I included a lot of print statements to make the agent's workflow and the LLM responses really transparent. Below, I will share one example of the model's performance scoring a middle school science question. More analysis of the performance will be the subject of a second blog post, so stay tuned!

The Test Input

I used released science content from the 2023 Texas STAAR assessment for 8th grade science, which included multiple science questions, multiple student responses for each question at different score levels, and a scoring guide for each question. You can see the science content here.

scoring_guide_1 = "Score 2: The student response includes: There are a total of 7 atoms representing three elements in the formula AND The elements are sodium (2 atoms), sulfur (1 atom), and oxygen (4 atoms). Score 1: The student answers half of the question correctly. 
Score 0: The response is incorrect or irrelevant."
question_1 = "Sodium sulfate (Na2SO4) is used to produce many products. Which elements are represented in the formula AND how many atoms of each element are represented in the formula?"

test_input_0 = {
    "question": question_1,
    "student_response": "13",
    "scoring_guide": scoring_guide_1     
}

result_0 = app.invoke(test_input_0)
print(result_0["output"])

The verbose output from this run is pasted below, and can be analyzed to see the agent run in its most simple form (A. Plan -> C. Score -> D. Verify). The agent determined that no fact checking was needed, so the web search tool was not used.

================== A. PLANNING SCORING APPROACH ==================
🧠 Generating new plan
**Summary:** 
- **Score 2:** Includes correct identification of all elements (sodium, sulfur, oxygen) and their respective atoms in sodium sulfate formula.
- **Score 1:** Provides half-correct answer either missing one of the elements with their atom count or misidentifying an element.
- **Score 0:** Incorrect or irrelevant response.

**Flowchart Plan:**
- **Step 1:** Identify if the student answers both parts of the question correctly (elements and atoms).
    - **IF** Student answers that there are sodium, sulfur, and oxygen elements AND
        - **THEN** Check if student mentions correct atom counts for each element.
            - **IF** Correct atom counts identified (2 sodium, 1 sulfur, 4 oxygen) 
                - **THEN** Assign Score 2
            - **ELSE**
                - **IF** Student identifies at least two elements correctly but not their corresponding atoms OR misses one element completely  
                    - **THEN** Assign Score 1
                - **ELSE**
                    - **IF** Answer contains no correct information about elements or atom counts, regardless of how many parts are addressed. 
                        - **THEN** Assign Score 0

================== C. SCORING STUDENT RESPONSE ==================
Scoring Output: SCORE: 0
EXPLANATION: The response does not identify the elements or their atom counts in sodium sulfate.

==================== D. VERIFYING SCORE ====================
Verification response: {
    "new_score": 0,
    "reason": "The response does not include any information about atoms, elements, or the formula."
}
OLD_SCORE: 0  -  NEW_SCORE: 0

******************** FINAL ANSWER *******************
SCORE: 0
EXPLANATION: The response does not identify the elements or their atom counts in sodium sulfate.

The output above shows that the agent created a scoring plan in the form of a structured flowchart, which it then used to score the student's response of "13", and give an explanation of why it assigned that score of 0 ("The response does not identify the elements or their atom counts in sodium sulfate."). In the verification node, it re-scored the response a 0, and since it assigned the same score twice, it was verified and returned as the final answer.

While this run shows the promise of the scoring agent in generating correct scores and reasonable explanations that align with the scoring guide, there is much more to explore. Additional tests in the Jupyter notebook include varied paths that the agent can take in scoring, and the varied outputs it produces. The next blog post will evaluate its performance in multiple questions and student responses, and reflect on my lessons learned to apply to future prototypes.

Nevertheless, Jesse Coded

Jesse Smith Byers — Mon, 08 Mar 2021 21:44:03 +0000

My story: I'm a 42 year old mother of two boys, and I started my career change from K-12 public education into software at age 40.

In March 2020, when I was one month away from graduating from a full-time immersive bootcamp, my kids' school shut down for the rest of the year. I started squeezing what should have been 8-10 hours of coding into the 5am-9am 4-hour time block each day, so I could start home-schooling at 9am. Nevertheless, I graduated on time.

The post-bootcamp job search looked a lot different for me than for my non-parent classmates, and I reflected on the struggles and came up with a system that worked for me at that time. I kept myself accountable through my (almost) weekly DEV posts. Until my son knocked over a full mug of coffee on my laptop. Nevertheless, I figured out a way to make it all work.

I learned that "making it work" means constantly revisiting your goals, and constantly re-calibrating what is feasible and desirable in any given time period. I adjusted my post-bootcamp career goals, and ended up combining my past experience in education with code to start working in software education. Because of the pandemic, I started working full-time with two boys at home. Nevertheless, it worked.

I was conflicted about this decision, and struggled with thoughts that I had somehow failed or given up by not ending this story with a title of "software engineer". Periodic reflection helps me realize that the "recipe" for career changing into tech has to be different for everyone, and DEV has been a great platform to foster my reflection about how I'm progressing in the field. Nevertheless, I still need reminders to keep reflecting.

Today, I work full-time in software ed, while freelancing part-time on educational software (in my non-existent free time). This gives me balance and fulfillment. And I realize how lucky I am to be able to juggle these roles, thanks to a supportive husband who has been doing our cooking, and moving to a new town where the kids have been attending in-person school 5 days a week since September. This has not been true for all of us this year.

Nevertheless. Despite the ups and downs and in and outs of my journey, I am now a software engineer AND I am an advocate for increasing access for more underrepresented folks in tech. This is actually the main part of my job description, and in the end, I am very proud of this outcome.

Therefore...

My advice for allies to support underrepresented folks who code is...

I have learned over the past year, as a bootcamp student, and now as a bootcamp employee, that one of the biggest keys to supporting underrepresented folks is flexibility:

We need flexible schedules so learning can happen at the times that work for us.
We need flexible structures that allow us to set our own goals and check them off, and revise them as needed, as we continuously juggle code and life.
We need flexible definitions of what success looks like, including the various roles that might be the best fit for us.

Happy International Women's Day, everyone!

Add Basic and Conditional Formatting to a Spreadsheet Using the Google Sheets API

Jesse Smith Byers — Tue, 05 Jan 2021 14:58:10 +0000

If you've just landed here, make sure you check out the previous articles to see how I wired up an old React application with Google Sign-in, so that it could generate new Google Sheets with the click of a button. In this article, I'll describe how I used vanilla JavaScript and the Google Sheets API to add basic formatting as well as conditional formatting to the cells of the spreadsheet.

Formatting Goals

For this project, I had two main goals for formatting. My first goal was to add some basic formatting that would be applied to cells basic on their position (for example, bolding the header rows and first column). My second goal was to add some conditional formatting - that is, formatting that would be applied to specific cells based on the value of that cell (or another cell, for that matter). After some research, I learned that I could apply both the basic formatting and conditional formatting within one function.

Setting Up the addFormatting Function

Here is the basic skeleton of the function to accomplish both types of formatting. In the next sections, I'll break down the request object for each type of formatting below.

export function addFormatting(spreadsheet) {
  var spreadsheetId = spreadsheet.spreadsheetId;
  var sheet1Id = spreadsheet.sheets[0].properties.sheetId
  var sheet2Id = spreadsheet.sheets[1].properties.sheetId

  var requests = [
    // add an object for each basic formatting rule

    //add an object for each conditional formatting rule
  ];

  var body = {requests: requests}

  window.gapi.client.sheets.spreadsheets.batchUpdate({
    spreadsheetId: spreadsheetId,
    resource: body
  }).then((response) => {
    console.log(`formatting and conditional formatting updated.`);
  });
}

In the addFormatting function, we start by defining some variables by pulling values out of the spreadsheet object that was passed into the function (spreadsheetId, sheet1Id, and sheet2Id).

Next, we will create an array of request objects that define all of the properties of the formatting we would like to update. The next two sections of the article will describe this in detail, but for now, we know that this will be an array of objects.

Once we have a requests array, we can define the body of our request by setting up an object with a key of "requests" pointing to the value of our requests array.

Finally, we are ready to make a call to the Google Sheets API using the spreadsheets.batchUpdate() method. Our argument is an object containing the spreadsheetId of the spreadsheet we are updating, as well as the body of our request. When a response is received, we can then call another function, or for now, just print a message to the console confirming that the formatting has been updated.

Below, I'll focus on how to create the request objects for updating basic formatting, as well as simple conditional formatting.

Basic Formatting Requests

In our skeleton addFormatting function above, we set up an empty requests array. To add basic formatting, we simply need to add an object that defines the properties of each style that we want to update. For example, the code below includes two request objects: One to make the header row text bold, and one to make the first column text bold.

  var requests = [

    // BOLD TEXT IN HEADER ROW
    { 
      repeatCell: {
        range: {
          sheetId: sheet1Id,
          startRowIndex: 0,
          endRowIndex: 1
        },
        cell: {
          userEnteredFormat: {
            textFormat: {
              bold: true
            }
          }
        },
        fields: "userEnteredFormat.textFormat.bold"
      }
    },

    // BOLD TEXT IN FIRST COLUMN
    { 
      repeatCell: {
        range: {
          sheetId: sheet1Id,
          startColumnIndex: 0,
          endColumnIndex: 1
        },
        cell: {
          userEnteredFormat: {
            textFormat: {
              bold: true
            }
          }
        },
        fields: "userEnteredFormat.textFormat.bold"
      }
    },

    // ADD ADDITIONAL REQUEST OBJECTS HERE
  ];

Let's break down the first request, to make the header row bold. First, we define the repeatCell property, which lets us set the range that the formatting will be applied to, which often includes the sheetId, startRowIndex, endRowIndex, startColumnIndex, and endRowIndex. The rows and columns are zero-indexed. In this example, we can leave out the column indices to apply the formatting across the entire row.

Next, we define the cell property, to define exactly what change we want to make to each cell that was defined in the repeatCell property. Finally, we need to define a fields property, which basically constrains the update to only the fields that we identify. Since we are only changing the text style in this request, we can set the field to fields: "userEnteredFormat.textFormat.bold".

You can learn more about basic formatting and check out some sample code on the Basic Formatting page of the Google Sheets API documentation. There is also a short video to help you get started.

Conditional Formatting Requests

Creating a conditional formatting request is fairly similar to creating a basic formatting request, but we will use a few different properties. Here is an example of two requests that will change the background color of a cell based upon the value within the cell:

  var requests = [

    //SET BACKGROUND COLOR TO GREEN IF VALUE <= 999,999
    { 
      addConditionalFormatRule: {
        rule: {
          ranges: [ {
            sheetId: sheet1Id,
            startRowIndex: 1,
            endRowIndex: 221,
            startColumnIndex: 1,
          },
          // add another range object if needed
         ],
          booleanRule: {
            condition: {
              type: 'NUMBER_LESS_THAN_EQ',
              values: [ { userEnteredValue: "999999" } ]
            },
            format: {
              backgroundColor: { green: 1.0 } 
            }
          }
        },
        index: 0
      }
    }, 

    //SET BACKGROUND COLOR TO RED IF VALUE > 1,000,000
    { 
      addConditionalFormatRule: {
        rule: {
          ranges: [ {
            sheetId: sheet1Id,
            startRowIndex: 1,
            endRowIndex: 220,
            startColumnIndex: 1,
          } ],
          booleanRule: {
            condition: {
              type: 'NUMBER_GREATER_THAN_EQ',
              values: [ { userEnteredValue: "1000000" } ]
            },
            format: {
              backgroundColor: { red: 1.0 } 
            }
          }
        },
        index: 1
      }
    }, 

    // ADD MORE CONDITIONAL FORMATTING REQUESTS HERE
  ];

Let's break down the first request. Each request starts with the property addConditionalFormatRule, and then explicitly defines the rule that will be applied. Similar to the basic formatting examples above, we can set the ranges to which the rule will be applied, in the form of an array including an object to define each range.

Next, we can define either a booleanRule (formatting applied based on whether a condition is true or false) or a gradientRule (formatting applied across a gradient, such as changing the color shade based on the value). You can learn more about the two types of rules here.

For our booleanRule, we need to set the condition that will be evaluated by setting the type (for example, NUMBER_LESS_THAN_EQ, and the values that will be checked. In the first example, values: [ { userEnteredValue: "999999" } ], indicates that within the identified range, any cell with a value that is less than or equal to 999,999 would have the formatting applied to it. The format is defined next: backgroundColor: { green: 1.0 }.

The last part of a conditional formatting request is the index, which defines the order in which each conditional formatting request would be applied. Again, indexing starts at zero.

The code above is just a simple example that shows how to apply background color based on the values within cells, but there is a lot more you can do using custom formulas, similar to what you can do working within a google sheet in your browser. To learn more, check out the Documentation for Conditional Formatting and the Code Samples for Conditional Formatting.

Create a Google Sheet and Write Data Using the Google Sheets API

Jesse Smith Byers — Sun, 03 Jan 2021 15:27:33 +0000

Prior Set-Up

As you'll recall from the previous articles, I created a GoogleDownload React component that was responsible for signing a user in to Google so that the application could have read/write access to their Google Sheets. That component included a button that, when clicked, would start the spreadsheet creation process: createGoogleSheet(). This is where we will start, and all of the logic described below will live in the sheets.js file.

Overall Process

Once inside the sheets.js file, our work will occur in 3 steps:

Create a new, blank spreadsheet in the user's Google Drive
Add data to the spreadsheet
Add basic styling and conditional formatting to the spreadsheet (see next article).

1. Create a New Spreadsheet

To create a new spreadsheet, we will use the spreadsheets.create method provided by the Google Sheets API. This method allows us to define the title, number of sheets, and some basic sheet properties for our spreadsheet. To learn more about creating new spreadsheets, you can reference the documentation for creating spreadsheets here, and check out the code samples as well.

export function createGoogleSheet(data) {
  var columns = [ "country", "cases", "todayCases", "deaths",   "todayDeaths",  "recovered", "todayRecovered",  "active", "critical",   "casesPerOneMillion",   "deathsPerOneMillion",  "tests",    "testsPerOneMillion",   "population", "activePerOneMillion", "recoveredPerOneMillion", "criticalPerOneMillion" ]

  var request = {
    properties: {
      title: "WORLD COVID DATA" 
    },
    sheets: [
      { //sheet1
        properties: {
          title: "Sheet1",
          gridProperties: {
            columnCount: columns.length, 
            rowCount: data.length + 1, 
            frozenRowCount: 1,
            frozenColumnCount: 1,
          },
          tabColor: { 
            red: 1.0,
            green: 0.3,
            blue: 0.4
          },
        },
      },
      { //sheet2
        properties: {
          title: "Sheet2",
          gridProperties: {
            columnCount: columns.length, 
            rowCount: data.length + 1, 
            frozenRowCount: 1,
            frozenColumnCount: 1,
          },
          tabColor: { 
            red: 0.0,
            green: 0.0,
            blue: 1.0
          },
        },
      },            
    ],
  }

  window.gapi.client.sheets.spreadsheets.create(request)
    .then((response) => {
      addDataValues(response, data, columns)
      const url = response.result.spreadsheetUrl
      window.open(url, "_blank")
    });
}

When this spreadsheet creation method is called when the download button is clicked, data to populate the spreadsheet is passed as an argument into the method. First, we define the variable columns to define the columns that will be included in the spreadsheet. These columns could be defined programmatically from the data passed in, hard-coded directly, or could be obtained by modifying the data object. In my case, I hard-coded the column names because my data was messy and I only wanted to include certain data points.

Next, we call the spreadsheets.create() method and pass in a request object and a callback function. Our request object includes all of the properties that will define our spreadsheet and the sheets within it. In this case, we are defining the spreadsheet title, we are defining two sheets within the spreadsheet, and setting the title, grid properties (column and row information), and tab color for each sheet.

When a response is received, it includes all of our spreadsheet information in the form of an object (response.result). we can trigger our next function to add data values to the currently blank spreadsheet, as well as call the window.open() function to open the Google Sheet in a new tab.

2. Add Data to the Spreadsheet

The addDataValues() function takes in the response object from the spreadsheet creation function, the data, and the columns array.

First, we need to define variables for the spreadsheet object and the spreadsheetId, both of which are pulled out of the response object.

Next, we have to work with our data and format it into a two-dimensional array in order to add it to the spreadsheet. The data should be transformed into the following format:

var values = [
  [column1header, column2header, column3header],
  [row2col1data, row2col2data, row2col3data],
  [row3col1data, row3col2data, row3col3data],
  // etc...
]

This can be done for each sheet individually. As you can see in the commented out code below, you could create a separate values array for valuesSheet1 and valuesSheet2.

Next, we create a data array, which includes the range and values for each "chunk" of data we are adding to the spreadsheet. In my example, I added a separate entry for sheet1 and sheet2.

Finally, we create a body object, which includes our data, as well as the valueInputOption value, which can be set to either "RAW" or "USER_ENTERED_VALUE".

Once the body object is defined, we are ready to call the spreadsheets.values.batchUpdate() method to update the spreadsheet with all of the data we have defined in the body object. After receiving a response, we can then call our final method, which will add styling and conditional formatting to the spreadsheet cells.

export function addDataValues(response, spreadsheetData, columns) {
  var spreadsheet = response.result
  var spreadsheetId = response.result.spreadsheetId;

  var valuesSheet1 = [columns]

  spreadsheetData.forEach(country => {
    var row = []
    columns.forEach(heading => {
      row.push(country[heading])
    })
    valuesSheet1.push(row)
  })

  // var valuesSheet2 = 

  var data = [];
  data.push(
    {
      range: "Sheet1",
      values: valuesSheet1
    },
    // {
      // range: "Sheet2",
      // values: valuesSheet2
    // }
  );

  var body = {
    data: data,
    valueInputOption: "USER_ENTERED"
  };

  window.gapi.client.sheets.spreadsheets.values.batchUpdate({
    spreadsheetId: spreadsheetId,
    resource: body
  }).then(() => addFormatting(spreadsheet));
}

To learn more about adding data values, check out the documentation on writing cell values and code samples for basic writing.

Almost done! Check out the next article in the series to see how to add basic and conditional formatting to the spreadsheet through the addFormatting(spreadsheet) method.

Create a Google Sheet from a React Application With One Click

Jesse Smith Byers — Wed, 30 Dec 2020 23:45:10 +0000

Check out the first article in this series for background on my project. In this article, I'll explain how I modified some existing resources to set up Google Sheets API integration with one of my old frontend-only React projects. If you want to follow along, try to implement the following steps into a new branch of one of your own existing React applications, and learn to export your data into a new sheet with one click!

1. Setting up Google Integration

First, you will need to set up a new Google Cloud Platform project and enable the Sheets API. Follow the directions under Step 1 of the Browser Quickstart Guide. At the end of this step, you will need to jot down your CLIENT_ID and API_KEY, which will be stored securely.

Note: The directions in Step 1 of the Browser Quickstart are misleading. Make sure you click on the "Create API key" button within your own Google Developer Console, and NOT from the Quickstart directions page!

2. Storing and Securing Secrets

Next, you will need to use dotenv to store and secure the CLIENT_ID and API_KEY. Install this dependency by running the following command in your terminal:

npm install dotenv

Create an empty .env file in your root directory. Next, make sure that you add .env to your .gitignore file, so that the .env file will not be tracked.

Now, you can store your CLIENT_ID and API_KEY in the .env file, like so:

REACT_APP_CLIENT_ID=<ENTER-YOUR-CLIENT-ID-HERE>
REACT_APP_API_KEY=<ENTER-YOUR-API-KEY-HERE>

In Step 5, we will be able to access these variables by requiring dotenv, and then using the process.env namespace to access the values:

require('dotenv').config()
process.env.REACT_APP_API_KEY
process.env.REACT_APP_CLIENT_ID

3. Modifying the index.html file

At the bottom of the body element of your index.html file, you will need to add a script element to connect to the Google APIs Client for JavaScript. See below:

<!DOCTYPE html>
<html lang="en">
  <head>
    ...
  </head>

  <body>

    <div id="root"></div>

    <!-- JAVASCRIPT GOOGLE CLIENT  -->
    <script async defer src="https://apis.google.com/js/api.js"></script>

  </body>
</html>

4. Update an Existing Component, and Pass Data as Props to New Component

Choose a component in your React application that already has access to the data that you want to include on your spreadsheet report. We will import a new GoogleDownload component into the existing component, and then render the new component, passing any data that will be included in the spreadsheet as props to the new GoogleDownload component.

...
import {GoogleDownload} from './GoogleDownload'

    ...

    return (
        <div>

            ...

            <GoogleDownload data={data}/>

        </div>
    )
}

5. Create a New Re-Usable GoogleDownload Component

In this step, you will create a component that includes three buttons, and all of the logic required to:

Sign in and authorize read and write access to a user's google sheets,
Sign out from google, and
Kick off the spreadsheet creation process.

Most of the code here is adapted from Step 2 of the Browser Quickstart Guide. However, I needed to make some modifications to convert the vanilla JavaScript into code that would integrate properly within a React component.

Here is the complete code for the re-usable GoogleDownload component, but I will break it down section by section below.

import React, { useEffect } from 'react';
import { createGoogleSheet } from '../spreadsheet/sheets'
require('dotenv').config()

export function GoogleDownload(data) {

    useEffect(() => {
        handleClientLoad();
    }, []);


     // On load, called to load the auth2 library and API client library.

      function handleClientLoad() {
        window.gapi.load('client:auth2', initClient);
      }

     // Initializes the API client library and sets up sign-in state listeners.

      function initClient() {
        window.gapi.client.init({
          apiKey: process.env.REACT_APP_API_KEY,
          clientId: process.env.REACT_APP_CLIENT_ID,
          discoveryDocs: ["https://sheets.googleapis.com/$discovery/rest?version=v4"],
          scope: "https://www.googleapis.com/auth/spreadsheets"
        }).then(function () {

          // Listen for sign-in state changes.
  window.gapi.auth2.getAuthInstance().isSignedIn.listen(updateSigninStatus);

          // Handle the initial sign-in state.
          updateSigninStatus(window.gapi.auth2.getAuthInstance().isSignedIn.get());
        }, function(error) {
            console.log(error) // add something for error handling
        });
      }

      // Called when the signed in status changes, to update the UI appropriately. After a sign-in, the API is called.

      function updateSigninStatus(isSignedIn) {
        var authorizeButton = document.getElementById('authorize_button');
        var signoutButton = document.getElementById('signout_button');
        var downloadButton = document.getElementById('download_button');

        if (isSignedIn) {
          authorizeButton.style.display = "none";
          signoutButton.style.display = "block";
          downloadButton.style.display = "block";
        } else {
          authorizeButton.style.display = "block";
          signoutButton.style.display = "none";
          downloadButton.style.display = "none";
        }
      }

      // Sign in the user upon button click.

      function handleAuthClick(event) {
        window.gapi.auth2.getAuthInstance().signIn();
      }

      // Sign out the user upon button click.

      function handleSignoutClick(event) {
        window.gapi.auth2.getAuthInstance().signOut();
      }




    return (
        <div>

            <button id="authorize_button"  onClick={handleAuthClick} display={updateSigninStatus} className="block googleauth">Authorize Google Login</button>

            <button id="signout_button"  onClick={handleSignoutClick} display={updateSigninStatus} className="block googlesignout">Sign Out of Google</button>

            <button id="download_button" onClick={() => createGoogleSheet(data.data)} className="block google" display={updateSigninStatus}>Download Data to Google Sheets</button> 

        </div>
    )
}

Here's what's happening, step=by-step:

First, set up your imports:

import React, { useEffect } from 'react';
import { createGoogleSheet } from '../spreadsheet/sheets'
require('dotenv').config()

Next, set up the skeleton of your functional component:

export function GoogleDownload(data) {

    useEffect(() => {
        ...
    }, []);

    ...

    return (
        <div>

          ...

        </div>
    )
}

Add functions to control the google authorization logic:

Note: These functions were largely pulled from Step 2 of the Browser Quickstart Guide, but I was unable to access gapi from within the React component. Instead, it can be accessed through the window object as window.gapi. In addition, I modified the logic for hiding and showing buttons based on signInStatus so that they would function in relation to React's update patterns.

     // On load, called to load the auth2 library and API client library.

      function handleClientLoad() {
        window.gapi.load('client:auth2', initClient);
      }

     // Initializes the API client library and sets up sign-in state listeners.

      function initClient() {
        window.gapi.client.init({
          apiKey: process.env.REACT_APP_API_KEY,
          clientId: process.env.REACT_APP_CLIENT_ID,
          discoveryDocs: ["https://sheets.googleapis.com/$discovery/rest?version=v4"],
          scope: "https://www.googleapis.com/auth/spreadsheets"
        }).then(function () {

          // Listen for sign-in state changes.
  window.gapi.auth2.getAuthInstance().isSignedIn.listen(updateSigninStatus);

          // Handle the initial sign-in state.
          updateSigninStatus(window.gapi.auth2.getAuthInstance().isSignedIn.get());
        }, function(error) {
            console.log(error) // add something for error handling
        });
      }

      // Called when the signed in status changes, to update the UI appropriately. After a sign-in, the API is called.

      function updateSigninStatus(isSignedIn) {
        var authorizeButton = document.getElementById('authorize_button');
        var signoutButton = document.getElementById('signout_button');
        var downloadButton = document.getElementById('download_button');

        if (isSignedIn) {
          authorizeButton.style.display = "none";
          signoutButton.style.display = "block";
          downloadButton.style.display = "block";
        } else {
          authorizeButton.style.display = "block";
          signoutButton.style.display = "none";
          downloadButton.style.display = "none";
        }
      }

      // Sign in the user upon button click.

      function handleAuthClick(event) {
        window.gapi.auth2.getAuthInstance().signIn();
      }

      // Sign out the user upon button click.

      function handleSignoutClick(event) {
        window.gapi.auth2.getAuthInstance().signOut();
      }

Call the handleClientLoad function within the useEffect hook:

This will check if the user is already signed in and authorized to access Google Sheets.

    useEffect(() => {
        handleClientLoad();
    }, []);

Add buttons for google sign in, sign out, and creating the spreadsheet:

Again, the first two buttons were adapted from Step 2 of the Browser Quickstart Guide, but slightly modified so that the updateSignInStatus() function would control the value of the display property. I also added onClick listeners to each button through JSX, rather than through vanilla JavaScript as in the Quickstart example. Finally, the download_button is wired up to call the createGoogleSheet() function when it is clicked, which is imported from sheets.js, and will pass the data needed for the spreadsheet as an argument.

            <button id="authorize_button"  onClick={handleAuthClick} display={updateSigninStatus} className="block googleauth">Authorize Google Login</button>

            <button id="signout_button"  onClick={handleSignoutClick} display={updateSigninStatus} className="block googlesignout">Sign Out of Google</button>

            <button id="download_button" onClick={() => createGoogleSheet(data.data)} className="block google" display={updateSigninStatus}>Download Data to Google Sheets</button>

At this point, the React application is completely wired up to integrate with the Google Sheets API, is able to sign in users and grant authorization to access Google Sheets, sign them out, and has passed data to the function that will create the spreadsheet. At this point, everything related to building the actual Google Sheets file will be completed in the sheets.js file, using vanilla JavaScript and guided by the documentation for the Google Sheets API.

If you'd like to check out my demo project, you can see the code here:

GoogleDownload component

Next Up: Creating and Updating a Spreadsheet Using the Google Sheets API

Check out the last article in this series to see how I started writing logic in the sheets.js file to create a spreadsheet, add data, and add basic as well as conditional formatting. Here's a quick preview of the Sheets.js file.

The Challenge: Create a Spreadsheet from a React Application?

Jesse Smith Byers — Wed, 30 Dec 2020 23:18:50 +0000

I recently signed on to build a small feature for an existing project, which involves developing the data reporting feature for a quiz app used by K-12 science teachers and students. As I had never explored data reporting in any of my applications before, I knew I had a lot of research and experimentation to do before jumping into the (somewhat unfamiliar) codebase of the application I would be working on.

Below, I'll share the first few steps of my research journey, and how I learned through experimentation with one of my existing apps. Then in the next two articles, I will share the solution I plan to implement in the science application.

The Specification

The application I will ultimately be working on is a quiz app that allows teachers to assign a quiz/activity to a group of students, the students can then individually complete the activity, and the class-level and individual results are stored in the database and can be displayed in the browser after the quiz is administered.

I was tasked with figuring out a way to export these class-level and individual results to a spreadsheet. I was given a sample spreadsheet of what the results should look like when the report is complete, which included two sheets, with quite a bit of custom styling and conditional formatting to help teachers understand and make instructional decisions based on the data. But beyond this example spreadsheet, I was given the freedom to decide which technologies to use to create the final product. The application was developed using a React/Next.js frontend and Node backend, with GraphQL.

My Research and Early Decisions

From the start, I knew that I could either develop an Excel-based solution or a Google Sheets-based solution. I suspected that the Excel-based solution might be easier to implement since it would likely not require authentication, whereas google-based solutions would require some variety of google sign-in or Oauth. However, as a former teacher, I know that most public schools run off of Google products, so integrating with Google Sheets would likely be the most teacher-friendly solution.

Option #1: excel4node

I briefly explored the excel4node package, and realized that my initial perception of Excel being the easier solution might not be accurate. I quickly learned that the spreadsheet would need to be created on the server side, and then sent to the client side. Once on the client side, there was quite a bit of code required to transform the workbook into a downloadable excel spreadsheet. I integrated this solution into one of my existing React apps, and found that all of the data I needed to access was already accessible in the frontend, so the server side work just felt very redundant. Therefore, I decided to move on to explore a Google Sheets solution.

However, if you're interested in going this route, check out the excel4node documentation and plan do do a lot of searching on StackOverflow to figure out various ways to download the workbook. If you'd like to see my messy experimentation, you can see my server-side code to create the Excel workbook here and my React component here.

import React from 'react';


const Excel = (data) => {

    // frontend code to download spreadsheet using axios for fetch and code to download excel spreadsheet
    function download(data) {
        const axios = require('axios');

        axios.get('/myreport', {responseType: 'blob'})
            .then(response => {
                let headerLine = response.headers['content-disposition'];
                let startFileNameIndex = headerLine.indexOf('"') + 1
                let endFileNameIndex = headerLine.lastIndexOf('"')
                let filename = headerLine.substring(startFileNameIndex, endFileNameIndex)
                const url = window.URL.createObjectURL(new Blob([response.data], 
                {type:'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'}));
                const link = document.createElement('a');

                link.href = url;
                link.setAttribute('download', filename);
                document.body.appendChild(link);
                link.click();
                link.remove();
            }).catch(error => {
                console.log(error)
            })
    }

    return <button onClick={download} className="block">Download Data to Excel</button>

}

export default Excel

After this messy experiment, I was ready to move on to option #2.

Option #2: Google Sheets API

When I started researching the Google Sheets API, I found that there was extensive documentation and some tutorials and sample code...but unfortunately none of the samples really suited my use case. The samples did show me that Google would be able to provide the right functionality, but I was essentially on my own to figure out how to make it work in the context of the application I would be working on. While the best tutorial example I found involved working on the server-side with Node.js, I started exploring what it might look like to generate and open a new Google Sheet from the frontend.

In the next article in the series, I'll outline the solution that worked in my demo application, which I plan to ultimately implement in the science application. You'll be able to follow along to create a Google Sheet with data from one of your own existing React applications. Check it out!

CS Ed Week! Block-Based Programming?

Jesse Smith Byers — Wed, 09 Dec 2020 18:56:25 +0000

Happy CS Ed Week!

I'm a former middle school science teacher career changer, now working in software...but I have to admit that #CSEdWeek played a large part in my transition into software. I started using Code.org tools such as AppLab and Hour of Code activities with my kids each year, then started incorporating other block-based programming tools into the curriculum, such as StarLogo Nova.

So naturally, I was excited to see this article, Block-based Programming in Computer Science Classrooms, which shares research on the experiences of kids who start out with block-based programming.

Did anyone else start out with block-based programming, for yourself, or using it with your kids or students?

What's your take - did it help with the transfer over to learning a programming language?

Any favorite block-based platforms to share?

D3 Building Blocks #4: SVG Groups

Jesse Smith Byers — Fri, 04 Dec 2020 17:05:41 +0000

Now that we can draw individual elements on the SVG, we can start to group them and apply attributes and styling to the entire group at once.

Groups

Imagine you are creating a document that has multiple drawings, with text associated with each drawing. As you start to format attributes and move items around, it would be helpful to group each drawing with its associated text, and apply styling to the collection all at once. This is what groups allow us to in our SVGs. They act a as a container that holds other SVG elements together.

Setting Up A Group to Apply Common Attributes

To create a group, simply use a <g> tag to enclose all of the elements that you would like to group together. Then, assign attributes to the group, rather than to the individual elements.

Example 1: Groups in HTML

<svg>
    <g fill="red" stroke="orange" stroke-width="3px">
      <circle cx="20" cy="30" r="15"></circle>
      <rect x="10" y="70" width="20" height="20"></rect>
    </g>

    <g fill="blue" stroke="green" stroke-width="5px">
      <circle cx="80" cy="30" r="15"></circle>
      <rect x="70" y="70" width="20" height="20"></rect>
    </g>
  </svg>

In the example above, we have set up two groups, which each include a circle and a rectangle element. Within each group, the circle and the rectangle have the same styling, since we applied the styling to the group rather than to the individual elements.

Example 2: Groups in D3

d3.select("svg")
  .append("g")
  .attr("id", "red");

d3.select("g#red")
  .append("circle")
  .attr("cx", 20)
  .attr("cy", 30)
  .attr("r", 15);

d3.select("g#red")
  .append("rect")
  .attr("x", 10)
  .attr("y", 70)
  .attr("width", 20)
  .attr("height", 20);

d3.select("g#red")
  .attr("fill", "red")
  .attr("stroke", "orange")
  .attr("stroke-width", "3px");


d3.select("svg")
  .append("g")
  .attr("id", "blue");

d3.select("g#blue")
  .append("circle")
  .attr("cx", 80)
  .attr("cy", 30)
  .attr("r", 15);

d3.select("g#blue")
  .append("rect")
  .attr("x", 70)
  .attr("y", 70)
  .attr("width", 20)
  .attr("height", 20);

d3.select("g#blue")
  .attr("fill", "blue")
  .attr("stroke", "green")
  .attr("stroke-width", "5px");

In the example above, we have created the same drawing including two groups, a red group and a blue group. Note how we can assign each group a different id in order to style each group individually. In this example, we have applied styling using the D3 attribute method, but this styling could also be applied using CSS.

Read the SVG documentation to learn more about the Scalable Vector Graphics group element.

SVG Group Element

D3 Building Blocks #3: SVG Shapes and Attributes

Jesse Smith Byers — Tue, 01 Dec 2020 15:04:44 +0000

Now that we've had an introduction to using D3 methods to represent HTML elements and CSS styling, it's time to explore Scalable Vector Graphics, or SVGs. In this post, we'll move beyond manipulating and styling text elements, and start to explore creating visual elements using lines and shapes.

Scalable Vector Graphics (SVGs)

A common issue that arises when working with images is scaling. We've all had the experience of trying to enlarge a photo or other image, only to have the resolution become blurry as it gets larger. This happens because most image files are based on pixels, and the number of pixels does not increase when we try to make it bigger, so the enlarged version looks less detailed. Scalable Vector Graphics, or SVGs, are images that are based on drawn paths in the HTML, rather than a collection of pixels. As a result, the quality or resolution of the image remains high even when it is enlarged.

The `<svg>` Element

In order to create an SVG, we can place an <svg> tag within our HTML code, or use our new D3 methods to create and append an <svg> element to the DOM.

Example 1: <svg> in HTML

<body>
  <svg>
    // contents of svg
  </svg>
</body>

Example 2: <svg> in D3

d3.select("body")
  .append("svg")

Attributes for the `<svg>`

The <svg> element is basically just a canvas, or drawing space within the DOM. We can set its viewport size by assigning values for the height and width properties, in pixels.

The <svg> coordinate plane has a horizontal x-axis, which starts at 0 at on the left and increments upwards to the right. The y-axis is vertical and starts at 0 at the top and increments up as you move downwards (this may feel counter-intuitive at first).

<body>
  <svg height="500" width="900">
    // contents of svg
  </svg>
</body>
// this svg element has a height of 500px and a width of 900px, and is located at the top left corner of the document

The height and width attributes can also be set using the D3 attr() method:

d3.select("svg")
  .attr("height", 500)
  .attr("width", 900)

A common convention, however, is to set the height and width as constants, and then pass the variable to set the value of these attributes. This makes it easier to make adjustments, since only the values of the constants need to be modified.

const height = 500
const width = 900

d3.select("svg")
  .attr("height", height)
  .attr("weight", weight)

Drawing Shapes

Once we have an <svg> element in the DOM, we can start drawing shapes within it. Below, we'll explore some of the most common shapes, and how to set their size and position through their attributes.

Circle

To draw a circle, we use the <circle> tag. To set the position of our circle on the <svg>, we can set the cx and cy attributes. If we do not specify these attributes, the center of the circle will be placed at the x=0, y=0 position on the <svg> canvas. To set the radius, we can set the r attribute.

<body>
  <svg>
    <circle cx="50" cy="30" r="10"></circle>
  </svg>
</body>

OR using D3 code:

d3.select("svg")
  .append("circle")
  .attr("cx", 50)
  .attr("cy", 30)
  .attr("r", 10)

Rectangle

We can draw rectangles by using the <rect> tag, and set the rectangle size using the width and height attributes, and set the position using the x and y attributes.

<body>
  <svg>
    <rect x="100" y="30" width="20" height="10"></rect>
  </svg>
</body>

OR using D3 code:

d3.select("svg")
  .append("rect")
  .attr("x", 100)
  .attr("y", 30)
  .attr("width", 20)
  .attr("height", 10)

Line

We can draw lines by using the <line> tag, and specifying the x and y coordinates of the endpoints of the line, as well as the stroke color.

<svg>
  <line x1="0" y1="0" x2="100" y2="100" stroke="red"></line>
</svg>

OR using D3 code:

d3.select("svg")
  .append("line")
  .style("stroke", "red")
  .attr("x1", 0)
  .attr("y1", 0) 
  .attr("x2", 100) 
  .attr("y2", 100)

Path

In SVG, a path is simply a collection of connected lines. To create a path, we can use the <path> tag and set the d attribute to specific the exact path of the line. The d attribute is a string that starts with an M (Move To), followed by the x and y coordinates of the starting point of the path. It is then followed by an L (Line To), and the x and y coordinates of the end point of the first line. We can then continue to add x and y coordinate pairs to create additional segments until the path is complete.

<svg>
  <path d="M100 50 L75 25 L100 0" stroke="green" fill="none"></path>
</svg>

OR using D3 code:

d3.select("svg")
  .append("path")
  .style("stroke", "green")
  .attr("d", "M100 50 L75 25 L100 0")

// path starts at 100,50
// then draws a line segment from 100,50 to 75,25
// then draws a line segment from 75,25 to 100,0

Read the SVG documentation to learn more about Scalable Vector Graphics elements and attributes.

D3 Building Blocks #2: Using D3 to Style Elements

Jesse Smith Byers — Mon, 30 Nov 2020 15:29:52 +0000

Using D3 to Style Elements

Now that we can select, add and remove elements from the DOM using D3, we can use additional methods to style those elements. We'll learn how to use the style() and attr() methods in this post.

style()

The style() method allows us to apply inline styling to a selection (or selections) we have made using the select or selectAll methods. This method takes two arguments: We first need to identify the name of the CSS property that we would like to add or change, and then specify the value of the change we are trying to make.

style() Syntax Examples

d3.select("p")
  .style("color", "red")

// OR //

let p = d3.select("p")

p.style("color", "green")
// Selects the <p> tag, and sets the text color to red

In the first example above, we are stringing the style method onto the selection method. Alternatively, we can save the selection to a variable, and call the style method on that variable, like the second example.

With either approach, we can add multiple styles to the same selection, as shown below.

d3.selectAll("h1")
  .style("color", "blue")
  .style("font-family", "Times New Roman")
  .style("font-size", "30px")
  .style("text-align", "center")
// Selects all of the <h1> elements, and sets the font to red, Times New Roman, 30px, and centers the text.

Beyond styling text, we can use the style() method to add styling to other elements such as shapes, lines, and areas. For example:

d3.select("span")
  .style("background-color", "yellow")
// selects the <span> element and applies a background color of yellow

d3.selectAll("circle")
  .style("fill", "purple")
//selects all of the circles and applies a purple fill

attr()

Similar to the previous method, the attr() method allows us to apply inline styling to specific attributes. As we start working with data in future posts, we'll be using this method to apply attributes to elements based on the values in our data. For now, we'll get comfortable with the syntax by using attr() to set basic attributes such as class names and id names.

Just as with style(), the attr() method takes in two arguments: the name of the attribute we are trying to set, and the value of that attribute.

attr() Syntax Examples

d3.selectAll("div")
  .attr("class", "card")
// Selects all of the <div> tags, and gives them each a class of "card"

d3.select("div")
  .attr("id", "root")
// Selects a div, and assigns it the "root" id attribute

As we will explore in future posts, there are many more attributes we can set using the attr() method once we start working with shapes and data, such as height, width, x and y coordinate locations, and radius size. In addition, we will learn how to use callback functions as our second argument in order to dynamically set attributes based on data values, which eventually allows to build complex visualizations using these D3 fundamental methods.

We are just scratching the surface with these methods! Use the resources below for a refresher on CSS fundamentals and styles that can be applied using D3:

MDN Web Docs:

Fundamental text and font styling

D3 Documentation:

Modifying Elements attr() and style()