From 2093d285edd92f4219b29811ddb0630f92383803 Mon Sep 17 00:00:00 2001 From: Zach Daniel Date: Sun, 7 Apr 2024 11:11:05 -0400 Subject: [PATCH] docs: move around some docs --- documentation/home.md | 1 + .../topics/{ => actions}/manual-actions.md | 2 +- .../{ => resources}/embedded-resources.md | 34 +++++++++---------- mix.exs | 10 +++--- 4 files changed, 24 insertions(+), 23 deletions(-) rename documentation/topics/{ => actions}/manual-actions.md (94%) rename documentation/topics/{ => resources}/embedded-resources.md (82%) diff --git a/documentation/home.md b/documentation/home.md index d5964c0e..0e43d959 100644 --- a/documentation/home.md +++ b/documentation/home.md @@ -45,6 +45,7 @@ Welcome to the Ash Framework documentation! Here you will find everything you ne - [Update Actions](documentation/topics/actions/update-actions.md) - [Destroy Actions](documentation/topics/actions/destroy-actions.md) - [Generic Actions](documentation/topics/actions/generic-actions.md) +- [Manual Actions](documentation/topics/actions/manual-actions.md) ### Security diff --git a/documentation/topics/manual-actions.md b/documentation/topics/actions/manual-actions.md similarity index 94% rename from documentation/topics/manual-actions.md rename to documentation/topics/actions/manual-actions.md index 9500aa89..d3b3bd5a 100644 --- a/documentation/topics/manual-actions.md +++ b/documentation/topics/actions/manual-actions.md @@ -6,7 +6,7 @@ Manual actions are a way to implement an action in a fully custom way. This can ## Manual Creates/Updates/Destroy -For manual create, update and destroy actions, a module is passed that uses one of the provided modules (Ash.Resource.ManualCreate, Ash.Resource.ManualUpdate and Ash.Resource.ManualDestroy). +For manual create, update and destroy actions, a module is passed that uses one of the following (`Ash.Resource.ManualCreate`, `Ash.Resource.ManualUpdate` and `Ash.Resource.ManualDestroy`). For example: diff --git a/documentation/topics/embedded-resources.md b/documentation/topics/resources/embedded-resources.md similarity index 82% rename from documentation/topics/embedded-resources.md rename to documentation/topics/resources/embedded-resources.md index b52b7f04..5cf60b3e 100644 --- a/documentation/topics/embedded-resources.md +++ b/documentation/topics/resources/embedded-resources.md @@ -1,8 +1,6 @@ # Embedded Resources -Embedded resources function very similarly to [embedded schemas in Ecto](https://hexdocs.pm/ecto/Ecto.Schema.html). -The primary difference is the same as the primary difference between Ecto schemas and Ash resources: the full lifecycle -of the resource is managed by its configuration. For example, you can add validations, calculations, and even authorization policies to an embedded resource. Here is an example of a simple embedded resource: +Embedded resources are stored as maps in attributes of other resources. They are great for storing structured data, and support a whole range of useful features that resources support. For example, you can have calculations, validations, policies and even relationships on embedded resources.Here is an example of a simple embedded resource: ```elixir defmodule MyApp.Profile do @@ -10,13 +8,14 @@ defmodule MyApp.Profile do data_layer: :embedded # Use the atom `:embedded` as the data layer. attributes do - attribute :first_name, :string - attribute :last_name, :string + attribute :first_name, :string, public?: true + attribute :last_name, :string, public?: true end end ``` -Embedded resources cannot have relationships or aggregates. +> ### embedded resources can't do everything {: .info} +> Embedded resources cannot have aggregates, or expression calculations that rely on data-layer-specific capabilities. It typically depends on the data layer what embedded resources can/can't do. ## Adding embedded resource attributes @@ -29,20 +28,20 @@ defmodule MyApp.User do attributes do ... - attribute :profile, MyApp.Profile - attribute :profiles, {:array, MyApp.Profile} # You can also have an array of embeds + attribute :profile, MyApp.Profile, public?: true + attribute :profiles, {:array, MyApp.Profile}, public?: true # You can also have an array of embeds end end ``` -## Nil values +## Handling nil values By default, all fields on an embedded resource will be included in the data layer, including keys with nil values. To prevent this, add the `embed_nil_values?` option to `use Ash.Resource`. For example: ```elixir defmodule YourEmbed do - use Ash.Resource, - data_layer: :embedded, + use Ash.Resource, + data_layer: :embedded, embed_nil_values?: false end ``` @@ -70,8 +69,8 @@ defmodule MyApp.Profile do data_layer: :embedded # Use the atom `:embedded` as the data layer. attributes do - attribute :first_name, :string - attribute :last_name, :string + attribute :first_name, :string, public?: true + attribute :last_name, :string, public?: true end validations do @@ -91,8 +90,8 @@ defmodule MyApp.Profile do data_layer: :embedded # Use the atom `:embedded` as the data layer. attributes do - attribute :first_name, :string - attribute :last_name, :string + attribute :first_name, :string, public?: true + attribute :last_name, :string, public?: true end calculations do @@ -106,6 +105,7 @@ defmodule MyApp.User do attributes do attribute :profile, MyApp.Profile do + public? true constraints [load: [:full_name]] end end @@ -139,8 +139,8 @@ defmodule MyApp.Tag do attributes do uuid_primary_key :id - attribute :name, :string - attribute :counter, :integer + attribute :name, :string, public?: true + attribute :counter, :integer, public?: true end validations do diff --git a/mix.exs b/mix.exs index aca0c656..0f4ad8f2 100644 --- a/mix.exs +++ b/mix.exs @@ -47,12 +47,14 @@ defmodule Ash.MixProject do "documentation/topics/about_ash/design-principles.md", "documentation/topics/about_ash/contributing-to-ash.md", "documentation/topics/resources/attributes.md", + "documentation/topics/resources/embedded-resources.md", "documentation/topics/actions/actions.md", "documentation/topics/actions/read-actions.md", "documentation/topics/actions/create-actions.md", "documentation/topics/actions/update-actions.md", "documentation/topics/actions/destroy-actions.md", "documentation/topics/actions/generic-actions.md", + "documentation/topics/actions/manual-actions.md", "documentation/topics/development/development-utilities.md", "documentation/topics/development/upgrading-to-3.0.md", "documentation/topics/security/actors-and-authorization.md", @@ -67,13 +69,11 @@ defmodule Ash.MixProject do "documentation/topics/resources/aggregates.md", "documentation/topics/resources/calculations.md", "documentation/topics/code-interface.md", - "documentation/topics/embedded-resources.md", "documentation/topics/extending-resources.md", "documentation/topics/expressions.md", "documentation/topics/reference/glossary.md", "documentation/topics/identities.md", "documentation/topics/managing-relationships.md", - "documentation/topics/manual-actions.md", "documentation/topics/monitoring.md", "documentation/topics/multitenancy.md", "documentation/topics/notifiers.md", @@ -103,6 +103,7 @@ defmodule Ash.MixProject do "documentation/topics/resources/attributes.md", "documentation/topics/resources/calculations.md", "documentation/topics/resources/aggregates.md" + "documentation/topics/resources/embedded-resources.md", ], Actions: [ "documentation/topics/actions/actions.md", @@ -110,7 +111,8 @@ defmodule Ash.MixProject do "documentation/topics/actions/create-actions.md", "documentation/topics/actions/update-actions.md", "documentation/topics/actions/destroy-actions.md", - "documentation/topics/actions/generic-actions.md" + "documentation/topics/actions/generic-actions.md", + "documentation/topics/actions/manual-actions.md", ], Security: [ "documentation/topics/security/actors-and-authorization.md", @@ -148,12 +150,10 @@ defmodule Ash.MixProject do "documentation/how_to/use-without-data-layers.md", "documentation/how_to/validate-changes.md", "documentation/topics/code-interface.md", - "documentation/topics/embedded-resources.md", "documentation/topics/extending-resources.md", "documentation/topics/expressions.md", "documentation/topics/identities.md", "documentation/topics/managing-relationships.md", - "documentation/topics/manual-actions.md", "documentation/topics/monitoring.md", "documentation/topics/multitenancy.md", "documentation/topics/notifiers.md",