Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

website: Expand data handling documentation with type-specific pages and examples #822

Merged
merged 9 commits into from
Aug 17, 2023
2 changes: 1 addition & 1 deletion .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ Code contributions that introduce new log messages should utilize the helper fun

- [`FrameworkError`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/internal/logging#FrameworkError) - Logs at `ERROR` level, can be used to provide additional detail alongside user-facing errors that are returned with [`diag.Diagnostics`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/diag#Diagnostics).
- [`FrameworkWarn`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/internal/logging#FrameworkWarn) - Logs at `WARN` level, can be used to signal unexpected scenarios that may not result in a user-facing error, but can be used to track down potential provider implementation bugs.
- [`FrameworkDebug`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/internal/logging#FrameworkDebug) - Logs at `DEBUG` level, can be used to describe internal logic behavior, such as [semantic equality](https://developer.hashicorp.com/terraform/plugin/framework/handling-data/custom-types#semantic-equality) being triggered to preserve a prior value, or a null `Computed` attribute being marked as unknown.
- [`FrameworkDebug`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/internal/logging#FrameworkDebug) - Logs at `DEBUG` level, can be used to describe internal logic behavior, such as [semantic equality](https://developer.hashicorp.com/terraform/plugin/framework/handling-data/types/custom#semantic-equality) being triggered to preserve a prior value, or a null `Computed` attribute being marked as unknown.
- [`FrameworkTrace`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/internal/logging#FrameworkTrace) - Logs at `TRACE` level, can be used to describe internal logic execution, such as logging a message before and after a provider-defined method is called. As the name suggests, these messages are used to "trace" where a program is at during execution.

More general guidance about logging can be found in the [Plugin Development documentation.](https://developer.hashicorp.com/terraform/plugin/log/managing)
Expand Down
135 changes: 125 additions & 10 deletions website/data/plugin-framework-nav-data.json
Original file line number Diff line number Diff line change
Expand Up @@ -131,11 +131,134 @@
},
{
"title": "Attributes",
"path": "handling-data/attributes"
"routes": [
{
"title": "Overview",
"path": "handling-data/attributes"
},
{
"title": "Bool",
"path": "handling-data/attributes/bool"
},
{
"title": "Float64",
"path": "handling-data/attributes/float64"
},
{
"title": "Int64",
"path": "handling-data/attributes/int64"
},
{
"title": "List",
"path": "handling-data/attributes/list"
},
{
"title": "List Nested",
"path": "handling-data/attributes/list-nested"
},
{
"title": "Map",
"path": "handling-data/attributes/map"
},
{
"title": "Map Nested",
"path": "handling-data/attributes/map-nested"
},
{
"title": "Number",
"path": "handling-data/attributes/number"
},
{
"title": "Object",
"path": "handling-data/attributes/object"
},
{
"title": "Set",
"path": "handling-data/attributes/set"
},
{
"title": "Set Nested",
"path": "handling-data/attributes/set-nested"
},
{
"title": "Single Nested",
"path": "handling-data/attributes/single-nested"
},
{
"title": "String",
"path": "handling-data/attributes/string"
}
]
},
{
"title": "Blocks",
"path": "handling-data/blocks"
"routes": [
{
"title": "Overview",
"path": "handling-data/blocks"
},
{
"title": "List Nested",
"path": "handling-data/blocks/list-nested"
},
{
"title": "Set Nested",
"path": "handling-data/blocks/set-nested"
},
{
"title": "Single Nested",
"path": "handling-data/blocks/single-nested"
}
]
},
{
"title": "Types",
"routes": [
{
"title": "Overview",
"path": "handling-data/types"
},
{
"title": "Bool",
"path": "handling-data/types/bool"
},
{
"title": "Float64",
"path": "handling-data/types/float64"
},
{
"title": "Int64",
"path": "handling-data/types/int64"
},
{
"title": "List",
"path": "handling-data/types/list"
},
{
"title": "Map",
"path": "handling-data/types/map"
},
{
"title": "Number",
"path": "handling-data/types/number"
},
{
"title": "Object",
"path": "handling-data/types/object"
},
{
"title": "Set",
"path": "handling-data/types/set"
},
{
"title": "String",
"path": "handling-data/types/string"
},
{
"title": "Custom Types",
"path": "handling-data/types/custom"
}
]
},
{
"title": "Paths",
Expand All @@ -152,14 +275,6 @@
{
"title": "Writing Data",
"path": "handling-data/writing-state"
},
{
"title": "Conversion Rules",
"path": "handling-data/conversion-rules"
},
{
"title": "Custom Types",
"path": "handling-data/custom-types"
}
]
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ func (r ThingResource) Create(ctx context.Context,
```

The configuration, plan, and state data is represented as an object, and
accessed like an object. Refer to the [conversion rules](/terraform/plugin/framework/handling-data/conversion-rules#converting-from-framework-types-to-go-types) for an
accessed like an object. Refer to the [object type](/terraform/plugin/framework/handling-data/types/object) documentation for an
explanation on how objects can be converted into Go types.

To descend into deeper nested data structures, the `types.List`, `types.Map`, and `types.Set` types each have an `ElementsAs()` method. The `types.Object` type has an `As()` method.
Expand Down Expand Up @@ -109,6 +109,3 @@ or null. It is safe to assume:

In any other circumstances, the provider is responsible for handling the
possibility that an unknown or null value may be presented to it.

Refer to the [conversion rules](/terraform/plugin/framework/handling-data/conversion-rules#converting-from-framework-types-to-go-types)
for more information about supported Go types.
Loading