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:

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:

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:

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:

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:

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:

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:

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 specifyformatter, 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:

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

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

Web UI Display

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

Report Generation

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 to efficiently fetch large datasets
• Explore Filtering to narrow down results

Updated 9 months ago