mirror of
https://github.com/ash-project/ash.git
synced 2024-09-20 05:23:03 +12:00
docs: sanitize things for docs
This commit is contained in:
parent
00433e648a
commit
c380cc1a14
13 changed files with 23 additions and 73 deletions
|
@ -1,31 +0,0 @@
|
|||
# taken from `attribute.always_select?`
|
||||
Useful if fields are used in read action preparations consistently.
|
||||
|
||||
A primary key attribute *cannot be deselected*, so this option will have no effect.
|
||||
|
||||
Generally, you should favor selecting the field that you need while running your preparation. For example:
|
||||
|
||||
```elixir
|
||||
defmodule MyApp.QueryPreparation.Thing do
|
||||
use Ash.Resource.Preparation
|
||||
|
||||
def prepare(query, _, _) do
|
||||
query
|
||||
# we use `ensure_selected` here because we don't want
|
||||
# to limit the fields being selected to only this attribute, rather
|
||||
# rather we want to make sure this field is definitely selected.
|
||||
|> Ash.Query.ensure_selected(:attribute_i_need)
|
||||
|> Ash.Query.after_action(fn query, results ->
|
||||
{:ok, Enum.map(results, fn result ->
|
||||
do_something_with_attribute_i_need(result)
|
||||
end)}
|
||||
end)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
This will prevent unnecessary fields from being selected.
|
||||
|
||||
|
||||
# Taken from `attribute.generated?`
|
||||
If it is, the data layer will know to read the value back after writing.
|
|
@ -524,8 +524,6 @@ Creating and using changesets can be verbose. Check out the {{link:ash:guide:Cod
|
|||
|
||||
See {{link:ash_postgres:guide:Get Started With Postgres:AshPostgres}} to see how to back your resources with postgres. This is highly recommended, as the postgres data layer provides tons of advanced capabilities.
|
||||
|
||||
See the {{link:ash:guide:Data Layers}} guide on how you might write your own data layer.
|
||||
|
||||
#### Add an API
|
||||
|
||||
Check out the AshJsonApi and AshGraphql extensions to effortlessly build APIs around your resources
|
||||
|
|
|
@ -1,10 +1,10 @@
|
|||
# Philosophy
|
||||
|
||||
The philosophy behind Ash allows us to build an extremely flexible and powerful set of tools, without locking users into specific choices at any level. The framework acts as a spinal cord for your application, with extension points at every level to allow for custom behavior. What are follows are the core tenets behind Ash Framework.
|
||||
The philosophy behind Ash allows us to build an extremely flexible and powerful set of tools, without locking users into specific choices at any level. The framework acts as a spinal cord for your application, with extension points at every level to allow for custom behavior. What follows are the core tenets behind Ash Framework.
|
||||
|
||||
## Anything, not Everything
|
||||
|
||||
"Anything, not Everything" means building a framework capable of doing anything, not providing a framework that already does everything. The first is possible, the second is not. Our primary goal is to provide a framework that *unlocks* potential, and frees developers to work on the things that makes their application special. To this end, there are many prebuilt extensions to use, but there is also a rich suite of tools to build your *own* extensions. In this way, you can make the framework work for you, instead of struggling to fit your application to a strictly proscribed pattern. Use as much of Ash as you can, and leverage the amazing Elixir ecosystem for everything else.
|
||||
"Anything, not Everything" means building a framework capable of doing anything, not providing a framework that already does everything. The first is possible, the second is not. Our primary goal is to provide a framework that *unlocks* potential, and frees developers to work on the things that make their application special. To this end, there are many prebuilt extensions to use, but there is also a rich suite of tools to build your *own* extensions. In this way, you can make the framework work for you, instead of struggling to fit your application to a strictly proscribed pattern. Use as much of Ash as you can, and leverage the amazing Elixir ecosystem for everything else.
|
||||
|
||||
## Declarative, Introspectable, Derivable
|
||||
|
||||
|
@ -12,7 +12,7 @@ The real superpower behind Ash is the declarative design pattern. All behavior i
|
|||
|
||||
## Pragmatism First
|
||||
|
||||
While Ash does have lofty goals and a roadmap, the priority for development is always what the *current* users of Ash need or are having trouble with. We focus on simple, pragmatic, and integrated solutions that meld well with the rest of the framework. A high priority is placed on ensuring that our users don't experience feature whip-lash due to poorly thought out implementations, and that any breaking changes(a fairly rare occurrence) have a clean and simple upgrade path. This is something made much easier by the declarative pattern,.
|
||||
While Ash does have lofty goals and a roadmap, the priority for development is always what the *current* users of Ash need or are having trouble with. We focus on simple, pragmatic, and integrated solutions that meld well with the rest of the framework. A high priority is placed on ensuring that our users don't experience feature whip-lash due to poorly thought out implementations, and that any breaking changes(a fairly rare occurrence) have a clean and simple upgrade path. This is something made much easier by the declarative pattern.
|
||||
|
||||
## Community
|
||||
|
||||
|
|
|
@ -1761,7 +1761,7 @@ defmodule Ash.Changeset do
|
|||
* `:create` - the records are created using the destination's primary create action
|
||||
* `{:create, :action_name}` - the records are created using the specified action on the destination resource
|
||||
* `{:create, :action_name, :join_table_action_name, [:list, :of, :join_table, :params]}` - Same as `{:create, :action_name}` but takes
|
||||
the list of params specified out and applies them when creating the join table row, with the provided join_table_action_name.
|
||||
the list of params specified out and applies them when creating the join record, with the provided join_table_action_name.
|
||||
* `:error` - an eror is returned indicating that a record would have been created
|
||||
* If `on_lookup` is set, and the data contained a primary key or identity, then the error is a `NotFound` error
|
||||
* Otherwise, an `InvalidRelationship` error is returned
|
||||
|
@ -1816,7 +1816,7 @@ defmodule Ash.Changeset do
|
|||
* belongs_to - an update action on the source resource
|
||||
* `{:relate_and_update, :action_name, :read_action_name}` - Same as the above, but customizes the read action called to search for matches.
|
||||
* `{:relate_and_update, :action_name, :read_action_name, [:list, :of, :join_table, :params]}` - Same as the above, but uses the provided list of parameters when creating
|
||||
the join row (only relevant for many to many relationships). Use `:all` to *only* update the join table row, and pass all parameters to its action
|
||||
the join row (only relevant for many to many relationships). Use `:all` to *only* update the join record, and pass all parameters to its action
|
||||
"""
|
||||
],
|
||||
on_match: [
|
||||
|
@ -1828,9 +1828,9 @@ defmodule Ash.Changeset do
|
|||
* `:update` - the record is updated using the destination's primary update action
|
||||
* `{:update, :action_name}` - the record is updated using the specified action on the destination resource
|
||||
* `{:update, :action_name, :join_table_action_name, [:list, :of, :params]}` - Same as `{:update, :action_name}` but takes
|
||||
the list of params specified out and applies them as an update to the join table row (only valid for many to many).
|
||||
the list of params specified out and applies them as an update to the join record (only valid for many to many).
|
||||
* `{:destroy, :action_name}` - the record is destroyed using the specified action on the destination resource. The action should be:
|
||||
* many_to_many - a destroy action on the join table
|
||||
* many_to_many - a destroy action on the join record
|
||||
* has_many - a destroy action on the destination resource
|
||||
* has_one - a destroy action on the destination resource
|
||||
* belongs_to - a destroy action on the destination resource
|
||||
|
|
|
@ -4,11 +4,7 @@ defmodule Ash.Resource.Dsl do
|
|||
describe: """
|
||||
Declares an attribute on the resource.
|
||||
""",
|
||||
links: [
|
||||
guides: [
|
||||
"ash:guide:Attributes"
|
||||
]
|
||||
],
|
||||
links: [],
|
||||
examples: [
|
||||
"""
|
||||
attribute :name, :string do
|
||||
|
@ -102,11 +98,7 @@ defmodule Ash.Resource.Dsl do
|
|||
describe: """
|
||||
A section for declaring attributes on the resource.
|
||||
""",
|
||||
links: [
|
||||
guides: [
|
||||
"ash:guide:Attributes"
|
||||
]
|
||||
],
|
||||
links: [],
|
||||
examples: [
|
||||
"""
|
||||
attributes do
|
||||
|
@ -204,9 +196,9 @@ defmodule Ash.Resource.Dsl do
|
|||
@many_to_many %Spark.Dsl.Entity{
|
||||
name: :many_to_many,
|
||||
describe: """
|
||||
Declares a many_to_many relationship. Many to many relationships require a join table.
|
||||
Declares a many_to_many relationship. Many to many relationships require a join resource.
|
||||
|
||||
A join table is typically a table who's primary key consists of one foreign key to each resource.
|
||||
A join resource is a resource that consists of a relationship to the source and destination of the many to many.
|
||||
""",
|
||||
links: [
|
||||
guides: [
|
||||
|
@ -224,7 +216,7 @@ defmodule Ash.Resource.Dsl do
|
|||
destination_attribute_on_join_resource :book_id
|
||||
end
|
||||
|
||||
# And in `BookWord` (the resource that defines the join table)
|
||||
# And in `BookWord` (the join resource)
|
||||
belongs_to :book, Book, primary_key?: true, required?: true
|
||||
belongs_to :word, Word, primary_key?: true, required?: true
|
||||
"""
|
||||
|
|
|
@ -61,9 +61,7 @@ defmodule Ash.Resource.Relationships.BelongsTo do
|
|||
[
|
||||
primary_key?: [
|
||||
type: :boolean,
|
||||
links: [
|
||||
guides: ["ash:guide:Attributes"]
|
||||
],
|
||||
links: [],
|
||||
default: false,
|
||||
doc:
|
||||
"Whether the generated attribute is, or is part of, the primary key of a resource."
|
||||
|
@ -71,18 +69,14 @@ defmodule Ash.Resource.Relationships.BelongsTo do
|
|||
required?: [
|
||||
type: :boolean,
|
||||
default: false,
|
||||
links: [
|
||||
guides: ["ash:guide:Attributes"]
|
||||
],
|
||||
links: [],
|
||||
doc:
|
||||
"Whether this relationship must always be present, e.g: must be included on creation, and never removed (it may be modified). The generated attribute will not allow nil values."
|
||||
],
|
||||
attribute_writable?: [
|
||||
type: :boolean,
|
||||
default: false,
|
||||
links: [
|
||||
guides: ["ash:guide:Attributes"]
|
||||
],
|
||||
links: [],
|
||||
doc: """
|
||||
Whether the generated attribute will be marked as public & writable.
|
||||
"""
|
||||
|
@ -90,9 +84,7 @@ defmodule Ash.Resource.Relationships.BelongsTo do
|
|||
define_attribute?: [
|
||||
type: :boolean,
|
||||
default: true,
|
||||
links: [
|
||||
guides: ["ash:guide:Attributes"]
|
||||
],
|
||||
links: [],
|
||||
doc:
|
||||
"If set to `false` an attribute is not created on the resource for this relationship, and one must be manually added in `attributes`, invalidating many other options."
|
||||
],
|
||||
|
@ -101,8 +93,7 @@ defmodule Ash.Resource.Relationships.BelongsTo do
|
|||
links: [
|
||||
modules: [
|
||||
"ash:module:Ash.Type"
|
||||
],
|
||||
guides: ["ash:guide:Attributes"]
|
||||
]
|
||||
],
|
||||
default: :uuid,
|
||||
doc: "The type of the generated created attribute."
|
||||
|
|
|
@ -86,7 +86,7 @@ defmodule Ash.Resource.Relationships.ManyToMany do
|
|||
type: :atom,
|
||||
links: [],
|
||||
doc:
|
||||
"The has_many relationship to the join table. Defaults to <relationship_name>_join_assoc"
|
||||
"The has_many relationship to the join resource. Defaults to <relationship_name>_join_assoc"
|
||||
]
|
||||
],
|
||||
@global_opts,
|
||||
|
|
|
@ -46,14 +46,14 @@ defmodule Ash.Resource.Transformers.ValidateRelationshipAttributes do
|
|||
raise Spark.Error.DslError,
|
||||
path: [:relationships, relationship.name],
|
||||
message:
|
||||
"Relationship `#{relationship.name}` expects source field on join table `#{relationship.source_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
|
||||
"Relationship `#{relationship.name}` expects source attribute on resource `#{relationship.source_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
|
||||
end
|
||||
|
||||
unless relationship.destination_attribute_on_join_resource in through_attributes do
|
||||
raise Spark.Error.DslError,
|
||||
path: [:relationships, relationship.name],
|
||||
message:
|
||||
"Relationship `#{relationship.name}` expects destination field on join table `#{relationship.destination_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
|
||||
"Relationship `#{relationship.name}` expects destination attribute on join resource `#{relationship.destination_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
2
mix.exs
2
mix.exs
|
@ -7,7 +7,7 @@ defmodule Ash.MixProject do
|
|||
designed to be used by multiple front ends.
|
||||
"""
|
||||
|
||||
@version "2.0.0-pre.8"
|
||||
@version "2.0.0-rc.0"
|
||||
|
||||
def project do
|
||||
[
|
||||
|
|
|
@ -534,7 +534,7 @@ defmodule Ash.Test.Actions.CreateTest do
|
|||
|> Api.create!()
|
||||
end
|
||||
|
||||
test "it updates the join table properly" do
|
||||
test "it updates the join resource properly" do
|
||||
post2 =
|
||||
Post
|
||||
|> new()
|
||||
|
|
|
@ -388,7 +388,7 @@ defmodule Ash.Test.Actions.UpdateTest do
|
|||
Post |> Ash.Query.sort(:title) |> Api.read!() |> Enum.map(& &1.title)
|
||||
end
|
||||
|
||||
test "it updates the join table properly" do
|
||||
test "it updates the join resource properly" do
|
||||
post =
|
||||
Post
|
||||
|> new(%{title: "title"})
|
||||
|
|
Loading…
Reference in a new issue