mirror of
https://github.com/ash-project/ash.git
synced 2024-09-08 05:51:11 +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
|
||||
|
||||
- [Project Structure](documentation/topics/development/project-structure.md)
|
||||
- [Generators](documentation/topics/development/generators.md)
|
||||
- [Testing](documentation/topics/development/testing.md)
|
||||
- [Development Utilities](documentation/topics/development/development-utilities.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
|
||||
|
||||
#### 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.
|
||||
|
||||
```bash
|
||||
|
|
|
@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.BaseResource do
|
|||
@moduledoc """
|
||||
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."
|
||||
use Igniter.Mix.Task
|
||||
|
|
|
@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Domain do
|
|||
@moduledoc """
|
||||
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"
|
||||
|
|
|
@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Enum do
|
|||
@moduledoc """
|
||||
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
|
||||
|
||||
|
|
|
@ -1,11 +1,20 @@
|
|||
defmodule Mix.Tasks.Ash.Gen.Resource do
|
||||
@moduledoc """
|
||||
Generate and configures an Ash.Resource.
|
||||
|
||||
## What changes take place?
|
||||
Generate and configure an Ash.Resource.
|
||||
|
||||
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
|
||||
|
||||
* `--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`
|
||||
"""
|
||||
|
||||
@shortdoc "Generate an Ash.Resource."
|
||||
@shortdoc "Generate and configure an Ash.Resource."
|
||||
use Igniter.Mix.Task
|
||||
|
||||
@impl Igniter.Mix.Task
|
||||
|
|
|
@ -2,7 +2,29 @@ defmodule Mix.Tasks.Ash.Patch.Extend do
|
|||
@moduledoc """
|
||||
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"
|
||||
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/writing-extensions.md",
|
||||
"documentation/topics/development/project-structure.md",
|
||||
"documentation/topics/development/generators.md",
|
||||
"documentation/topics/development/error-handling.md",
|
||||
"documentation/topics/development/testing.md",
|
||||
"documentation/topics/development/development-utilities.md",
|
||||
|
|
Loading…
Reference in a new issue