# Field Formatting

## Overview

All scalar fields in the Finale GraphQL API support the `formatter` argument, which controls how field values are returned. This allows you to choose between HTML-formatted output (with links and formatting), raw values, abbreviated versions, or other formatting options.

## Universal Support

**Important:** The `formatter` argument is available on **all scalar fields**, regardless of their type or default formatting behavior. This is a universal feature of the API.

## Formatter Options

Every scalar field accepts these formatter values:

### "html"

Returns HTML-formatted content with links and escaped text. This is useful for display in web interfaces.

**Example:**

```graphql
query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId(formatter: "html")
        sku(formatter: "html")
      }
    }
  }
}
```

**Use when:**

- Displaying data in a web UI that can render HTML
- You want clickable links for IDs
- You need properly escaped content for security

### "none"

Returns the raw, unformatted value exactly as stored in the database.

**Example:**

```graphql
query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId(formatter: "none")
        price(formatter: "none")
      }
    }
  }
}
```

**Use when:**

- Processing data programmatically
- You need the exact stored value
- Building integrations or exports
- You want to avoid HTML markup

### "abbreviated"

Returns an abbreviated or shortened version of the formatted value.

**Example:**

```graphql
query {
  productViewConnection(first: 5) {
    edges {
      node {
        description(formatter: "abbreviated")
        notes(formatter: "abbreviated")
      }
    }
  }
}
```

**Use when:**

- Displaying data in space-constrained UIs (tables, lists)
- You need a summary or preview
- Performance is critical and full formatting is expensive

### "blank-zero"

Returns an empty string if the value is zero, otherwise returns the formatted value.

**Example:**

```graphql
query {
  productViewConnection(first: 5) {
    edges {
      node {
        quantityOnHand(formatter: "blank-zero")
        price(formatter: "blank-zero")
      }
    }
  }
}
```

**Use when:**

- Displaying numeric fields where zero should appear empty
- Creating cleaner reports and tables
- Following business rules that treat zero as "not applicable"

### Default Formatter

When no `formatter` argument is specified, the API uses the field's default formatting behavior:

- Fields with HTML formatting capabilities typically default to standard formatting (not HTML)
- Some fields (like IDs, names, links) may have "html" as their default formatter
- Most fields use standard formatting by default

You can check each field's default formatter in its documentation under "Default Formatter" in the reference pages.

## Usage Patterns

### Field-Level Formatting

Apply formatting to individual fields:

```graphql
query {
  orderViewConnection(first: 10) {
    edges {
      node {
        orderId(formatter: "html")      # HTML formatted
        orderDate(formatter: "none")     # Raw value
        total(formatter: "blank-zero")   # Empty if zero
        description                      # Default formatting
      }
    }
  }
}
```

### Node-Level Formatting

Apply the same formatter to all fields in a node:

```graphql
query {
  productViewConnection(first: 10) {
    edges {
      node(formatter: "html") {
        productId    # All fields use HTML formatting
        sku
        name
        description
      }
    }
  }
}
```

**Note:** Field-level formatters override node-level formatters.

### Mixing Formatters

Combine node-level and field-level formatters for fine-grained control:

```graphql
query {
  orderViewConnection(first: 10) {
    edges {
      node(formatter: "html") {
        orderId                    # Uses node-level "html"
        orderDate(formatter: "none")  # Overrides to "none"
        customerId                 # Uses node-level "html"
        total(formatter: "blank-zero")  # Overrides to "blank-zero"
      }
    }
  }
}
```

## Default Formatter Behavior

Some fields have a default formatter defined (usually "html"). When a field has a default formatter:

- **If you don't specify**`formatter`, the field uses its default formatter
- **To get raw value**, explicitly use `formatter: "none"`
- **To use a different format**, specify the formatter you want

**Example with field that defaults to HTML:**

```graphql
query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId                    # Uses default (html)
        productId(formatter: "none")  # Gets raw value
        sku                          # Uses default (standard)
      }
    }
  }
}
```

## Best Practices

1. **Use "none" for integrations**: When building integrations or exports, use `formatter: "none"` to get exact values without formatting
2. **Use "html" for web display**: When displaying data in a web UI, use `formatter: "html"` for properly formatted and linked content
3. **Check default formatters**: Review field documentation to understand default formatting behavior
4. **Be explicit in production**: Always specify formatters explicitly in production code to avoid surprises if defaults change
5. **Consider performance**: The "none" formatter is typically fastest since it skips formatting logic

## Common Use Cases

### Data Export

```graphql
query {
  productViewConnection(first: 1000) {
    edges {
      node(formatter: "none") {
        productId
        sku
        name
        price
        quantityOnHand
      }
    }
  }
}
```

### Web UI Display

```graphql
query {
  orderViewConnection(first: 50) {
    edges {
      node(formatter: "html") {
        orderId
        orderDate
        customerName
        total
        status
      }
    }
  }
}
```

### Report Generation

```graphql
query {
  productViewConnection(first: 100) {
    edges {
      node {
        productId(formatter: "html")
        sku(formatter: "none")
        quantityOnHand(formatter: "blank-zero")
        description(formatter: "abbreviated")
      }
    }
  }
}
```

## Technical Details

### Implementation

The formatter argument is:

- Available on all scalar fields (String, Int, Float, Boolean, Date, etc.)
- Not available on relation fields or connection fields
- Processed on the server side before returning data
- Applies formatting based on the field's dimension definition

### Performance Considerations

- **Fastest**: "none" - skips all formatting logic
- **Standard**: default formatter - applies basic formatting
- **Slowest**: "html" - applies HTML escaping, link generation, and formatting

For large queries, consider using "none" and applying formatting client-side if needed.

## Next Steps

- Browse the sidebar navigation to see default formatters for each field
- Learn about [Pagination](https://developer.finaleinventory.com/reference/graphql-pagination) to efficiently fetch large datasets
- Explore [Filtering](https://developer.finaleinventory.com/reference/graphql-filtering) to narrow down results

Updated 9 months ago