> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useponder.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Actions

> In this guide we will cover information on how to setup some of the most common actions

### Navigating the user

You can set an action that uses `router.push` or `window.location` to navigate the user to a different web page.
If you need to pass in parameters - one way of doing that is to include them in the query of the url

```javascript example

const ponder = usePonder();
const goToSearchPage = (query) => {

    const url = `/search?query=${query}`;
    window.location.href = url;
}


ponder.setActions([
    {
        name: "goToSearchPage"
        description: "Call this function when the user needs to search for an item in the catalogue"
        arguments: ["name": "query", "type": "string", "required": true]
    }
])

ponder.onFunctionCall((name, args) => {
    if(name == "goToSearchPage"){
        goToSearchPage(args.query)
    }
})

```

### Scroll to an element

You can set an action that uses the `scrollIntoView` function on a ref that will scroll the view to the desired element

```javascript example
import { useRef } from 'react'

const ponder = usePonder();
const buyButtonRef = useRef();

const scrollToBuyButton = () => {
    if (buyButtonRef.current) {
        buyButtonRef.current.scrollIntoView({ behavior: 'smooth' });
    }
}

ponder.setActions([
    {
        name: "scrollToBuyButton",
        description: "Call this function when the user asks where they can buy the item.",
        arguments: []
    }
])

ponder.onFunctionCall((name, args) => {
    if (name == "scrollToBuyButton"){
        scrollToBuyButton()
    }
})

// ..rest of your code

<button ref={buyButtonRef}>Buy Now</button>

```

### Enforcing structure or format

When getting information from the user, it is often required that the information be ingested in a specific format. <br />

For example for providing a date, there are multiple ways users can say the date - "7th May 2025" or "May the 7th this year" etc.
In such cases, you can provide the format in which you want the date to be in the description of the action.

```javascript example

const ponder = usePonder();
const submitDate = (date) => {
    console.log(date) // <-- will always have YYYY-MM-DD format
}


ponder.setActions([
    {
        name: "submitDate"
        description: "Call this function when the user needs to provide a date. Make sure the format of the date is YYYY-MM-DD"
        arguments: ["name": "date", "type": "string", "required": true]
    }
])

ponder.onFunctionCall((name, args) => {
    if (name == "submitDate"){
        submitDate(args.date)
    }
})

```

### Controlling agent behaviour based on function output

Often times you might want the agent to say or act in a specific manner based on the output of the function. In such cases, the return of the function can include
instructions for the agent on how to handle the outcome. For example, in our submitDate example, we can tell the agent to tell the user to provide a date after 2025.

```javascript example

const ponder = usePonder();
const submitDate = (date) => {
    console.log(date) // <-- will always have YYYY-MM-DD format

    // your date handling logic

    if (date.year < 2025) {
        return {status: "failure", message: "Tell the user to only provide dates after 1 Jan 2025"}
    }
    else {
        return {status: "success", message: "Say nothing."}
    }
}


ponder.setActions([
    {
        name: "submitDate"
        description: "Call this function when the user needs to provide a date. Make sure the format of the date is YYYY-MM-DD"
        arguments: ["name": "date", "type": "string", "required": true]
    }
])

ponder.onFunctionCall((name, args) => {
    if (name == "submitDate"){
        return submitDate(args.date)
    }
})

```

The return object can have any structure you choose—you may add your own keys as needed. The underlying language model is flexible enough to interpret custom return formats.

### Interacting with the backend

You can pass an action that calls your backend via a `fetch` call or any other http library of your choice.

```javascript example

const ponder = usePonder();
const getOrderInfo = async (orderId) => {
    const response = await fetch(BACKEND_URL + "/get_order_info", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({ orderId })
    });
    const data = await response.json();
    if (data.orderData){
        //.. do something with the data

        return {status: "success", message: "Tell the user that the order has been successfully imported"}
    }
    else{
        return {status: "failure", message: "Order not found"}
    }
}


ponder.setActions([
    {
        name: "getOrderInfo"
        description: "Call this function when the user needs to see their order status"
        arguments: ["name": "orderId", "type": "string", "required": true]
    }
])

ponder.onFunctionCall(async (name, args) => {
    if (name == "getOrderInfo"){
        const result = await getOrderInfo(args.orderId)
        return result
    }
})

```