Fields

Introduction

Fields represent the type and characteristics of your stream data. For example a "name" field would likely be a string field type.

Fields are strictly concerned with data. Please see the UI package for configuring field inputs.

Defining Fields

Fields can be defined within the JSON configuration for your streams. You can get started by simply defining fields by handle and their type respectively.

Basic Example

In streams/contacts.json:

{
    "fields": [
        {
            "handle": "title",
            "type": "string"
        }
    ]
}

Full Example

To define more information about the field use an array:

In streams/contacts.json:

{
    "fields": [
        {
            "handle": "title",
            "name": "Title",
            "description": "The title of the film.",
            "type": "string",
            "rules": ["min:4"],
            "config": {
                "default": "Untitled"
            },
            "example": "Star Wars: The Force Awakens",
            "protected": false
        }
    ]
}

Field Validation

Define Laravel validation rules for fields and they will be merged the stream validation rules.

In streams/contacts.json:

{
    "fields": [
        {
            "handle": "name",
            "type": "string",
            "rules": ["required", "max:100"]
        },
        {
            "handle": "email",
            "type": "email",
            "rules": ["required", "email:rfc,dns"]
        },
        {
            "handle": "company",
            "type": "string",
            "rules": ["required", "unique"]
        }
    ]
}

Basic Usage

Values are stored as an image source

Image::make($entry->profile_image)->url();

Field Decorators

Field decorators provide expanded function to entry attributes like a universal presenter.

The below example demonstrates the image field decorator:

$entry->decorate('profile_image')->url();

You may also use magic methods derived from "camel casing" the field's handle to invoke decoration.

$entry->profileImage()->url();

Field Types

The field type is responsible for validating, casting, and more for its specific data type. These are the 24 types registered by Core (streams.core.field_types); apps and addons can register more. Each example is a complete field in list form, so it validates against the stream definition schema.

String

{
    "handle": "title",
    "type": "string"
}

URL

{
    "handle": "website",
    "type": "url"
}

UUID

"default": true in config generates a UUID when the attribute is missing.

{
    "handle": "id",
    "type": "uuid",
    "config": {
        "default": true
    }
}

Hash

{
    "handle": "password",
    "type": "hash"
}

Slug

config.separator sets the word separator (default -).

{
    "handle": "slug",
    "type": "slug",
    "config": {
        "separator": "-"
    }
}

Email

{
    "handle": "email",
    "type": "email"
}

Encrypted

{
    "handle": "api_token",
    "type": "encrypted"
}

Color

Values are stored lowercase and must parse as a color. The decorator adds hex(), rgb(), rgba(), and the individual channels; config.format picks the default output (hex).

{
    "handle": "brand_color",
    "type": "color"
}

Number

{
    "handle": "rating",
    "type": "number"
}

Integer

{
    "handle": "age",
    "type": "integer"
}

Decimal

config.precision rounds to that many decimal places.

{
    "handle": "price",
    "type": "decimal",
    "config": {
        "precision": 2
    }
}

Boolean

{
    "handle": "published",
    "type": "boolean"
}

Date

config.format is the storage format (default Y-m-d).

{
    "handle": "birthday",
    "type": "date"
}

Time

config.format defaults to H:i:s; config.timezone defaults to app.timezone.

{
    "handle": "opens_at",
    "type": "time"
}

Datetime

config.format defaults to Y-m-d H:i:s; config.timezone defaults to app.timezone.

{
    "handle": "published_at",
    "type": "datetime",
    "config": {
        "timezone": "UTC"
    }
}

Enum

enum is an alias of select. Both need config.options.

{
    "handle": "size",
    "type": "enum",
    "config": {
        "options": {
            "sm": "Small",
            "lg": "Large"
        }
    }
}

Select

{
    "handle": "status",
    "type": "select",
    "config": {
        "options": {
            "draft": "Draft",
            "live": "Live"
        }
    }
}

Multiselect

{
    "handle": "tags",
    "type": "multiselect",
    "config": {
        "options": {
            "news": "News",
            "guides": "Guides"
        }
    }
}

Array

config.items lists the allowed item types. Each item must pass at least one of them. Set config.enforce_items to false to skip the check, or use config.related (or config.stream) to cast items to entries of a stream.

{
    "handle": "scores",
    "type": "array",
    "config": {
        "items": [
            {"type": "string"},
            {"type": "number"}
        ]
    }
}

Object

config.allowed lists the value types an object may be. Each item names a stream (an entry of that stream), a generic class, or a prototype class. Without allowed, any object is accepted.

{
    "handle": "address",
    "type": "object",
    "config": {
        "allowed": [
            {"stream": "addresses"},
            {"generic": "Illuminate\\Support\\Collection"}
        ]
    }
}

File

The value is a path string. The decorator adds file helpers. Core does not restrict file types; add Laravel rules for that.

{
    "handle": "attachment",
    "type": "file"
}

Image

A file whose decorator works with the image manager.

{
    "handle": "profile_image",
    "type": "image"
}

Relationship

config.related names the related stream. related next to type is ignored. Add "multiple": true to store a list of keys, and key_name if the related stream is not keyed by id.

{
    "handle": "author_id",
    "type": "relationship",
    "config": {
        "related": "authors"
    }
}

Polymorphic

Stores a reference to an entry of any stream as {"@stream": "posts", "id": "..."} and restores the entry when read. config.related optionally documents the streams you expect; Core does not enforce it.

{
    "handle": "commentable",
    "type": "polymorphic",
    "config": {
        "related": ["posts", "pages"]
    }
}