mirror of
https://github.com/ash-project/ash.git
synced 2024-09-19 13:03:02 +12:00
improvement: update getting started guide and document generators
This commit is contained in:
parent
885727fb87
commit
0129285340
9 changed files with 117 additions and 8 deletions
|
@ -81,6 +81,7 @@ Welcome! Here you will find everything you need to know to get started with and
|
||||||
### Development
|
### Development
|
||||||
|
|
||||||
- [Project Structure](documentation/topics/development/project-structure.md)
|
- [Project Structure](documentation/topics/development/project-structure.md)
|
||||||
|
- [Generators](documentation/topics/development/generators.md)
|
||||||
- [Testing](documentation/topics/development/testing.md)
|
- [Testing](documentation/topics/development/testing.md)
|
||||||
- [Development Utilities](documentation/topics/development/development-utilities.md)
|
- [Development Utilities](documentation/topics/development/development-utilities.md)
|
||||||
- [Upgrading to 3.0](documentation/topics/development/upgrading-to-3.0.md)
|
- [Upgrading to 3.0](documentation/topics/development/upgrading-to-3.0.md)
|
||||||
|
|
16
documentation/topics/development/generators.md
Normal file
16
documentation/topics/development/generators.md
Normal file
|
@ -0,0 +1,16 @@
|
||||||
|
# Generators
|
||||||
|
|
||||||
|
Ash comes with multiple generators, packages as mix tasks, to help you generate and make modifications to your applications.
|
||||||
|
|
||||||
|
See the documentation for each mix task for more information. What is presented here is merely an overview.
|
||||||
|
|
||||||
|
## Generators
|
||||||
|
|
||||||
|
- `mix ash.gen.resource` - Generates a new `Ash.Resource`
|
||||||
|
- `mix ash.gen.domain` - Generates a new `Ash.Domain`
|
||||||
|
- `mix ash.gen.enum` - Generates a new `Ash.Type.Enum`
|
||||||
|
- `mix ash.gen.base_resource` - Generates a new base resource.
|
||||||
|
|
||||||
|
## Patchers
|
||||||
|
|
||||||
|
- `mix ash.patch.extend` - Adds an extension or extensions to a domain or resource.
|
|
@ -40,6 +40,54 @@ The actions we will be able to take on these resources include:
|
||||||
|
|
||||||
### Create a new project
|
### Create a new project
|
||||||
|
|
||||||
|
#### Using Igniter
|
||||||
|
|
||||||
|
First, to use `mix igniter.new`, the archive must be installed.
|
||||||
|
|
||||||
|
To install it, run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mix archive.install hex igniter_new
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, create a new project:
|
||||||
|
|
||||||
|
```elixir
|
||||||
|
mix igniter.new helpdesk --install ash && cd helpdesk
|
||||||
|
```
|
||||||
|
|
||||||
|
It is a good idea to make it a git repository and commit the initial project. You'll be able to see what changes we made, and can save your changes once we're done.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run in your terminal
|
||||||
|
git init
|
||||||
|
git add -A
|
||||||
|
git commit -m "first commit"
|
||||||
|
git branch -M main
|
||||||
|
```
|
||||||
|
|
||||||
|
Open the project in your text editor, and we'll get started.
|
||||||
|
|
||||||
|
You can skip to [Building your first Ash Domain](#building-your-first-ash-domain).
|
||||||
|
|
||||||
|
> ### Want to skip to the end? {: .warning}
|
||||||
|
>
|
||||||
|
> Add the `--example` flag to get the example code add directly to your app!
|
||||||
|
>
|
||||||
|
> ```bash
|
||||||
|
> mix igniter.new helpdesk --install ash --example
|
||||||
|
> ```
|
||||||
|
>
|
||||||
|
> Already know you want to use `AshPostgres`? Use the `--extend` argument.
|
||||||
|
>
|
||||||
|
> ```bash
|
||||||
|
> mix igniter.new helpdesk --install ash --example --extend postgres`
|
||||||
|
> ```
|
||||||
|
>
|
||||||
|
> If you generate this code, you can browse the rest of the guide, but the code shown will already be present in your application 🥳
|
||||||
|
|
||||||
|
#### Using Mix
|
||||||
|
|
||||||
We first create a new project with the `--sup` flag to add a supervision tree. This will be necessary for other follow-up tutorials.
|
We first create a new project with the `--sup` flag to add a supervision tree. This will be necessary for other follow-up tutorials.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|
|
@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.BaseResource do
|
||||||
@moduledoc """
|
@moduledoc """
|
||||||
Generates a base resource
|
Generates a base resource
|
||||||
|
|
||||||
For example: `mix ash.gen.base_resource The.Resource.Name`
|
## Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mix ash.gen.base_resource MyApp.Resource
|
||||||
|
```
|
||||||
"""
|
"""
|
||||||
@shortdoc "Generates a base resource. This is a module that you can use instead of `Ash.Resource`, for consistency."
|
@shortdoc "Generates a base resource. This is a module that you can use instead of `Ash.Resource`, for consistency."
|
||||||
use Igniter.Mix.Task
|
use Igniter.Mix.Task
|
||||||
|
|
|
@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Domain do
|
||||||
@moduledoc """
|
@moduledoc """
|
||||||
Generates an Ash.Domain
|
Generates an Ash.Domain
|
||||||
|
|
||||||
For example: `mix ash.gen.domain The.Domain`
|
## Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mix ash.gen.domain MyApp.Accounts
|
||||||
|
```
|
||||||
"""
|
"""
|
||||||
|
|
||||||
@shortdoc "Generates an Ash.Domain"
|
@shortdoc "Generates an Ash.Domain"
|
||||||
|
|
|
@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Enum do
|
||||||
@moduledoc """
|
@moduledoc """
|
||||||
Generates an Ash.Type.Enum
|
Generates an Ash.Type.Enum
|
||||||
|
|
||||||
For example `mix ash.gen.enum The.Enum.Name list,of,values`
|
## Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mix ash.gen.enum MyApp.Support.Ticket.Types.Status open,closed --short-name ticket_status
|
||||||
|
```
|
||||||
|
|
||||||
## Options
|
## Options
|
||||||
|
|
||||||
|
|
|
@ -1,11 +1,20 @@
|
||||||
defmodule Mix.Tasks.Ash.Gen.Resource do
|
defmodule Mix.Tasks.Ash.Gen.Resource do
|
||||||
@moduledoc """
|
@moduledoc """
|
||||||
Generate and configures an Ash.Resource.
|
Generate and configure an Ash.Resource.
|
||||||
|
|
||||||
## What changes take place?
|
|
||||||
|
|
||||||
If the domain does not exist, we create it. If it does, we add the resource to it if it is not already present.
|
If the domain does not exist, we create it. If it does, we add the resource to it if it is not already present.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mix ash.gen.resource Helpdesk.Support.Ticket \
|
||||||
|
--default-actions read
|
||||||
|
--uuid-primary-key id
|
||||||
|
--attribute subject:string:required:public
|
||||||
|
--relationship belongs_to:representative:Helpdesk.Support.Representative \
|
||||||
|
--extend postgres,graphql
|
||||||
|
```
|
||||||
|
|
||||||
## Options
|
## Options
|
||||||
|
|
||||||
* `--attribute` or `-a` - An attribute or comma separated list of attributes to add, as `name:type`. Modifiers: `primary_key`, `public`, and `required`. i.e `-a name:string:required`
|
* `--attribute` or `-a` - An attribute or comma separated list of attributes to add, as `name:type`. Modifiers: `primary_key`, `public`, and `required`. i.e `-a name:string:required`
|
||||||
|
@ -18,7 +27,7 @@ defmodule Mix.Tasks.Ash.Gen.Resource do
|
||||||
* `--base` or `-b` - The base module to use for the resource. i.e `-b Ash.Resource`. Requires that the module is in `config :your_app, :base_resources`
|
* `--base` or `-b` - The base module to use for the resource. i.e `-b Ash.Resource`. Requires that the module is in `config :your_app, :base_resources`
|
||||||
"""
|
"""
|
||||||
|
|
||||||
@shortdoc "Generate an Ash.Resource."
|
@shortdoc "Generate and configure an Ash.Resource."
|
||||||
use Igniter.Mix.Task
|
use Igniter.Mix.Task
|
||||||
|
|
||||||
@impl Igniter.Mix.Task
|
@impl Igniter.Mix.Task
|
||||||
|
|
|
@ -2,7 +2,29 @@ defmodule Mix.Tasks.Ash.Patch.Extend do
|
||||||
@moduledoc """
|
@moduledoc """
|
||||||
Adds an extension or extensions to the domain/resource
|
Adds an extension or extensions to the domain/resource
|
||||||
|
|
||||||
For example: `mix ash.patch.extend My.Domain.Resource Ash.Policy.Authorizer`
|
Extensions can either be a fully qualified module name, or one of the following list, based on the thing being extended
|
||||||
|
|
||||||
|
### Ash.Domain
|
||||||
|
|
||||||
|
- `json_api` - `AshJsonApi.Domain`
|
||||||
|
- `graphql` - `AshGraphql.Domain`
|
||||||
|
|
||||||
|
### Ash.Resource
|
||||||
|
|
||||||
|
- `postgres` - `AshPostgres.DataLayer`
|
||||||
|
- `sqlite` - `AshSqlite.DataLayer`
|
||||||
|
- `mysql` - `AshMysql.DataLayer`
|
||||||
|
- `ets` - `Ash.DataLayer.Ets`
|
||||||
|
- `mnesia` - `Ash.DataLayer.Mnesia`
|
||||||
|
- `embedded` - `data_layer: :embedded`
|
||||||
|
- `json_api` - `AshJsonApi.Resource`
|
||||||
|
- `graphql` - `AshGraphql.Resource`
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mix ash.patch.extend My.Domain.Resource postgres,Ash.Policy.Authorizer
|
||||||
|
```
|
||||||
"""
|
"""
|
||||||
@shortdoc "Adds an extension or extensions to the given domain/resource"
|
@shortdoc "Adds an extension or extensions to the given domain/resource"
|
||||||
require Igniter.Code.Common
|
require Igniter.Code.Common
|
||||||
|
|
1
mix.exs
1
mix.exs
|
@ -72,6 +72,7 @@ defmodule Ash.MixProject do
|
||||||
"documentation/topics/advanced/multitenancy.md",
|
"documentation/topics/advanced/multitenancy.md",
|
||||||
"documentation/topics/advanced/writing-extensions.md",
|
"documentation/topics/advanced/writing-extensions.md",
|
||||||
"documentation/topics/development/project-structure.md",
|
"documentation/topics/development/project-structure.md",
|
||||||
|
"documentation/topics/development/generators.md",
|
||||||
"documentation/topics/development/error-handling.md",
|
"documentation/topics/development/error-handling.md",
|
||||||
"documentation/topics/development/testing.md",
|
"documentation/topics/development/testing.md",
|
||||||
"documentation/topics/development/development-utilities.md",
|
"documentation/topics/development/development-utilities.md",
|
||||||
|
|
Loading…
Reference in a new issue