doc/tutorial: add skeleton and initial posts (#1317)

This commit is contained in:
Ariel Mashraki
2021-03-09 21:44:03 +02:00
committed by GitHub
parent 2a17dba983
commit 712d0e1b53
13 changed files with 480 additions and 147 deletions

View File

@@ -40,7 +40,7 @@ go mod init <project>
Go to the root directory of your project, and run:
```console
ent init User
go run entgo.io/ent/cmd/ent init User
```
The command above will generate the schema for `User` under `<project>/ent/schema/` directory:

View File

@@ -17,7 +17,6 @@ There are 5 types of mutations:
- `DeleteOne` - Delete a node from the graph.
- `Delete` - Delete all nodes that match a predicate.
<br>
Each generated node type has its own type of mutation. For example, all [`User` builders](crud.md#create-an-entity), share
the same generated `UserMutation` object.

View File

@@ -125,8 +125,7 @@ with admin role. We will create 2 additional packages for the purpose of the exa
- `rule` - for holding the different privacy rules in our schema.
- `viewer` - for getting and setting the user/viewer who's executing the operation. In this simple example, it can be
either a normal user or an admin.
<br/>
After running the code-generation (with the feature-flag for privacy), we add the `Policy` method with 2 generated policy rules.
```go

View File

@@ -11,7 +11,6 @@ and can contain the following configurations:
- Entity edges (or relations), like: `User`'s groups, or `User`'s friends.
- Database specific options, like: indexes or unique indexes.
<br/>
Here's an example of a schema:
```go

View File

@@ -56,8 +56,6 @@ The following types are currently supported by the framework:
- `UUID` (SQL only).
- `Other` (SQL only).
<br/>
```go
package schema

130
doc/md/tutorial-setup.md Executable file
View File

@@ -0,0 +1,130 @@
---
id: tutorial-setup
title: Setting Up
sidebar_label: Setting Up
---
This guide is intended for first-time users who want instructions on how to set up an Ent project from scratch.
Before we get started, make sure you have the following prerequisites installed on your machine.
## Prerequisites
- [Go](https://golang.org/doc/install)
- [Docker](https://docs.docker.com/get-docker) (optional)
After installing these dependencies, create a directory for the project and initialize a Go module:
```console
mkdir todo
cd $_
go mod init todo
```
## Installation
Run the following Go commands to install Ent, and tell it to initialize the project structure along with a `Todo` schema.
```console
go get entgo.io/ent/cmd/ent
```
```console
go run entgo.io/ent/cmd/ent init Todo
```
After installing Ent and running `ent init`, your project directory should look like this:
```console
.
├── ent
│ ├── generate.go
│ └── schema
│ └── todo.go
├── go.mod
└── go.sum
```
The `ent` directory holds the generated assets (see the next section), and the `ent/schema` directory contains your
entity schemas.
## Code Generation
When we ran `ent init Todo` above, a schema named `Todo` was created in the `todo.go` file under the`todo/ent/schema/` directory:
```go
package schema
import "entgo.io/ent"
// Todo holds the schema definition for the Todo entity.
type Todo struct {
ent.Schema
}
// Fields of the Todo.
func (Todo) Fields() []ent.Field {
return nil
}
// Edges of the Todo.
func (Todo) Edges() []ent.Edge {
return nil
}
```
As you can see, initially, the schema has no fields or edges defined. Let's run the command for generating assets to interact with
the `Todo` entity:
```console
go generate ./ent
```
## Create a Test Case
Running `go generate ./ent` invoked Ent's automatic code generation tool, which uses the schemas we define in our `schema` package to generate the actual Go code which we will now use to interact with a database. At this stage, you can find under `./ent/client.go`, client code that is capable of querying and mutating the `Todo` entities. Let's create a
[testable example](https://blog.golang.org/examples) to use this. We'll use [SQLite](https://github.com/mattn/go-sqlite3)
in this test-case for testing Ent.
```console
go get github.com/mattn/go-sqlite3
touch example_test.go
```
Paste the following code in `example_test.go` that instantiates an `ent.Client` and automatically creates all schema resources
in the database (tables, columns, etc).
```go
package main
import (
"context"
"log"
"todo/ent"
"entgo.io/ent/dialect"
_ "github.com/mattn/go-sqlite3"
)
func Example_Todo() {
// Create an ent.Client with in-memory SQLite database.
client, err := ent.Open(dialect.SQLite, "file:ent?mode=memory&cache=shared&_fk=1")
if err != nil {
log.Fatalf("failed opening connection to sqlite: %v", err)
}
defer client.Close()
ctx := context.Background()
// Run the automatic migration tool to create all schema resources.
if err := client.Schema.Create(ctx); err != nil {
log.Fatalf("failed creating schema resources: %v", err)
}
// Output:
}
```
Then, run `go test` to verify that everything works as expected.
```console
go test
```
After setting up our project, we're ready to create our Todo list.

194
doc/md/tutorial-todo-crud.md Executable file
View File

@@ -0,0 +1,194 @@
---
id: tutorial-todo-crud
title: Queries and Mutations
sidebar_label: Queries and Mutations
---
After setting up our project, we're ready to create our Todo list and query it.
## Create a Todo
Let's create a Todo in our testable example. We do it by adding the following code to `example_test.go`:
```go
func Example_Todo() {
// ...
task1, err := client.Todo.Create().Save(ctx)
if err != nil {
log.Fatalf("failed creating a todo: %v", err)
}
fmt.Println(task1)
// Output:
// Todo(id=1)
}
```
Running `go test` should pass successfully.
## Add Fields To The Schema
As you can see, our Todos are too boring as they contain only the `ID` field. Let's improve this example by adding
multiple fields to the schema in `todo/ent/schema/todo.go`:
```go
func (Todo) Fields() []ent.Field {
return []ent.Field{
field.Text("text").
NotEmpty(),
field.Time("created_at").
Default(time.Now).
Immutable(),
field.Enum("status").
Values("in_progress", "completed").
Default("in_progress"),
field.Int("priority").
Default(0),
}
}
```
After adding these fields, we need to run the code-generation as before:
```console
go generate ./ent
```
As you may notice, all fields have a default value on creation except the `text` field, which must be provided by
the user. Let's change our `example_test.go` to follow these changes:
```go
func Example_Todo() {
// ...
task1, err := client.Todo.Create().SetText("Add GraphQL Example").Save(ctx)
if err != nil {
log.Fatalf("failed creating a todo: %v", err)
}
fmt.Printf("%d: %q\n", task1.ID, task1.Text)
task2, err := client.Todo.Create().SetText("Add Tracing Example").Save(ctx)
if err != nil {
log.Fatalf("failed creating a todo: %v", err)
}
fmt.Printf("%d: %q\n", task2.ID, task2.Text)
// Output:
// 1: "Add GraphQL Example"
// 2: "Add Tracing Example"
}
```
Wonderful! We created a schema in the database with 5 columns (`id`, `text`, `created_at`, `status`, `priority`)
and created 2 items in our todo list, by inserting 2 rows to the table.
![tutorial-todo-create](https://entgo.io/assets/tutorial-todo-create-items.png)
## Add Edges To The Schema
Lets say we want to design our todo list so that an item can depend on another item. Therefore, we'll add a `parent`
edge to each Todo item, to get the item it depends on, and a back-reference edge named `children` in order to get all
items that depend on it.
Let's change our schema again in `todo/ent/schema/todo.go`:
```go
func (Todo) Edges() []ent.Edge {
return []ent.Edge{
edge.To("parent", Todo.Type).
Unique().
From("children"),
}
}
```
After adding these edges, we need to run the code-generation as before:
```console
go generate ./ent
```
## Connect 2 Todos
We continue our edges example, by updating the 2 todo items we just created. We define that item-2 (*"Add Tracing Example"*)
depends on item-1 (*"Add GraphQL Example"*).
![tutorial-todo-create](https://entgo.io/assets/tutorial-todo-create-edges.png)
```go
func Example_Todo() {
// ...
if err := task2.Update().SetParent(task1).Exec(ctx); err != nil {
log.Fatalf("failed connecting todo2 to its parent: %v", err)
}
// Output:
// 1: "Add GraphQL Example"
// 2: "Add Tracing Example"
}
```
## Query Todos
After connecting item-2 to item-1, we're ready to start querying our todo list.
**Query all todo items**:
```go
func Example_Todo() {
// ...
// Query all todo items.
items, err := client.Todo.Query().All(ctx)
if err != nil {
log.Fatalf("querying todos: %v", err)
}
for _, t := range items {
fmt.Printf("%d: %q\n", t.ID, t.Text)
}
// Output:
// 1: "Add GraphQL Example"
// 2: "Add Tracing Example"
}
```
**Query all todo items that depend on other items**:
```go
func Example_Todo() {
// ...
// Query all todo items that depend on other items.
items, err := client.Todo.Query().Where(todo.HasParent()).All(ctx)
if err != nil {
log.Fatalf("querying todos: %v", err)
}
for _, t := range items {
fmt.Printf("%d: %q\n", t.ID, t.Text)
}
// Output:
// 2: "Add Tracing Example"
}
```
**Query all todo items that don't depend on other items and have items that depend on them**:
```go
func Example_Todo() {
// ...
// Query all todo items that don't depend on other items and have items that depend them.
items, err := client.Todo.Query().
Where(
todo.Not(
todo.HasParent(),
),
todo.HasChildren(),
).
All(ctx)
if err != nil {
log.Fatalf("querying todos: %v", err)
}
for _, t := range items {
fmt.Printf("%d: %q\n", t.ID, t.Text)
}
// Output:
// 1: "Add GraphQL Example"
}
```
---
Please note that this documentation is under active development and supposed to be expanded in the near future.

View File

@@ -1,8 +1,9 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
* Copyright 2019-present Facebook Inc. All rights reserved.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
* This source code is licensed under the Apache 2.0 license found
* in the LICENSE file in the root directory of this source tree.
*
* @format
*/

View File

@@ -1,8 +1,9 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
* Copyright 2019-present Facebook Inc. All rights reserved.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
* This source code is licensed under the Apache 2.0 license found
* in the LICENSE file in the root directory of this source tree.
*
* @format
*/

View File

@@ -35,5 +35,11 @@
"faq",
"feature-flags"
]
},
"tutorial": {
"Tutorial": [
"tutorial-setup",
"tutorial-todo-crud"
]
}
}

View File

@@ -1,8 +1,9 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
* Copyright 2019-present Facebook Inc. All rights reserved.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
* This source code is licensed under the Apache 2.0 license found
* in the LICENSE file in the root directory of this source tree.
*
* @format
*/
@@ -12,142 +13,129 @@
// List of projects/orgs using your project for the users page.
const users = [
{
caption: 'User1',
// You will need to prepend the image path with your baseUrl
// if it is not '/', like: '/test-site/img/image.jpg'.
image: '/img/undraw_open_source.svg',
infoLink: 'https://www.faceboo.com',
pinned: true,
},
{
caption: 'User1',
// You will need to prepend the image path with your baseUrl
// if it is not '/', like: '/test-site/img/image.jpg'.
image: '/img/undraw_open_source.svg',
infoLink: 'https://www.facebook.com',
pinned: true,
},
];
const siteConfig = {
title: 'ent', // Title for your website.
tagline: 'An entity framework for Go',
url: 'https://entgo.io', // Your website URL
baseUrl: '/', // Base URL for your project */
title: 'ent', // Title for your website.
tagline: 'An entity framework for Go',
url: 'https://entgo.io', // Your website URL
baseUrl: '/', // Base URL for your project */
// Used for publishing and more
projectName: 'ent',
organizationName: 'facebook',
// Used for publishing and more
projectName: 'ent',
organizationName: 'facebook',
customDocsPath: 'md',
// For no header links in the top nav bar -> headerLinks: [],
headerLinks: [
{doc: 'getting-started', label: 'Docs'},
{href: 'https://pkg.go.dev/entgo.io/ent?tab=doc', label: 'GoDoc'},
{href: 'https://github.com/ent/ent', label: 'Github'},
{ blog: true, label: 'Blog' },
],
// If you have users set above, you add it here:
users,
/* path to images for header/footer */
headerIcon: 'img/logo.png',
favicon: 'img/favicon.ico',
/* Colors for website */
colors: {
primaryColor: '#85daff',
secondaryColor: '#4d8eaa',
},
/* Custom fonts for website */
/*
fonts: {
myFont: [
"Times New Roman",
"Serif"
customDocsPath: 'md',
// For no header links in the top nav bar -> headerLinks: [],
headerLinks: [
{doc: 'getting-started', label: 'Docs'},
{doc: 'tutorial-setup', label: 'Tutorial'},
{href: 'https://pkg.go.dev/entgo.io/ent?tab=doc', label: 'GoDoc', external: true },
{href: 'https://github.com/ent/ent', label: 'Github', external: true },
{blog: true, label: 'Blog' },
],
myOtherFont: [
"-apple-system",
"system-ui"
]
},
*/
// This copyright info is used in /core/Footer.js and blog RSS/Atom feeds.
copyright: `Copyright ${new Date().getFullYear()} Facebook Inc.`,
// If you have users set above, you add it here:
users,
highlight: {
// Highlight.js theme to use for syntax highlighting in code blocks.
theme: 'androidstudio',
hljs: function(hljs) {
hljs.registerLanguage('gotemplate', function(hljs) {
var GO_KEYWORDS = {
keyword:
'break default func interface select case map struct chan else goto package switch ' +
'const fallthrough if range type continue for import return var go defer ' +
'bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 ' +
'uint16 uint32 uint64 int uint uintptr rune with define block end',
literal:
'true false iota nil',
built_in: 'append cap close complex copy imag len make new panic print println real recover delete' +
'printf fail slice dict list'
};
return {
name: 'GoTemplate',
aliases: ['gotmpl'],
keywords: GO_KEYWORDS,
contains: [
hljs.COMMENT('{{-* */\\*', '\\*/ *-*}}'),
hljs.C_LINE_COMMENT_MODE,
{
className: 'string',
variants: [
hljs.QUOTE_STRING_MODE,
hljs.APOS_STRING_MODE,
{begin: '`', end: '`'},
]
},
{
begin: /:=/
},
]
};
});
/* path to images for header/footer */
headerIcon: 'img/logo.png',
favicon: 'img/favicon.ico',
/* Colors for website */
colors: {
primaryColor: '#85daff',
secondaryColor: '#4d8eaa',
},
// This copyright info is used in /core/Footer.js and blog RSS/Atom feeds.
copyright: `Copyright ${new Date().getFullYear()} Facebook Inc.`,
highlight: {
// Highlight.js theme to use for syntax highlighting in code blocks.
theme: 'androidstudio',
hljs: function(hljs) {
hljs.registerLanguage('gotemplate', function(hljs) {
var GO_KEYWORDS = {
keyword:
'break default func interface select case map struct chan else goto package switch ' +
'const fallthrough if range type continue for import return var go defer ' +
'bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 ' +
'uint16 uint32 uint64 int uint uintptr rune with define block end',
literal:
'true false iota nil',
built_in: 'append cap close complex copy imag len make new panic print println real recover delete' +
'printf fail slice dict list'
};
return {
name: 'GoTemplate',
aliases: ['gotmpl'],
keywords: GO_KEYWORDS,
contains: [
hljs.COMMENT('{{-* */\\*', '\\*/ *-*}}'),
hljs.C_LINE_COMMENT_MODE,
{
className: 'string',
variants: [
hljs.QUOTE_STRING_MODE,
hljs.APOS_STRING_MODE,
{begin: '`', end: '`'},
]
},
{
begin: /:=/
},
]
};
});
}
},
// Add custom scripts here that would be placed in <script> tags.
scripts: [
'https://buttons.github.io/buttons.js',
'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
'/js/code-block-buttons.js',
'/js/custom.js',
],
// On page navigation for the current documentation page.
onPageNav: 'separate',
// No .html extensions for paths.
cleanUrl: true,
// Open Graph and Twitter card images.
ogImage: 'img/undraw_online.svg',
twitterImage: 'img/undraw_tweetstorm.svg',
// For sites with a sizable amount of content, set collapsible to true.
// Expand/collapse the links and subcategories under categories.
// docsSideNavCollapsible: true,
// Show documentation's last contributor's name.
// enableUpdateBy: true,
// Show documentation's last update time.
// enableUpdateTime: true,
// You may provide arbitrary config keys to be used as needed by your
// template. For example, if you need your repo's URL...
// repoUrl: 'https://github.com/facebook/test-site',
gaTrackingId: 'UA-189726777-1',
algolia: {
apiKey: 'bfc8175da1bd5078f1c02e5c8a6fe782',
indexName: 'entgo',
}
},
// Add custom scripts here that would be placed in <script> tags.
scripts: [
'https://buttons.github.io/buttons.js',
'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
'/js/code-block-buttons.js',
'/js/custom.js',
],
// On page navigation for the current documentation page.
onPageNav: 'separate',
// No .html extensions for paths.
cleanUrl: true,
// Open Graph and Twitter card images.
ogImage: 'img/undraw_online.svg',
twitterImage: 'img/undraw_tweetstorm.svg',
// For sites with a sizable amount of content, set collapsible to true.
// Expand/collapse the links and subcategories under categories.
// docsSideNavCollapsible: true,
// Show documentation's last contributor's name.
// enableUpdateBy: true,
// Show documentation's last update time.
// enableUpdateTime: true,
// You may provide arbitrary config keys to be used as needed by your
// template. For example, if you need your repo's URL...
// repoUrl: 'https://github.com/facebook/test-site',
gaTrackingId: 'UA-189726777-1',
algolia: {
apiKey: 'bfc8175da1bd5078f1c02e5c8a6fe782',
indexName: 'entgo',
}
};
module.exports = siteConfig;

View File

@@ -99,6 +99,15 @@ in the LICENSE file in the root directory of this source tree.
.sideNavVisible .headerWrapper.wrapper header > a {
display: none!important;
}
.navigationSlider .slidingNav ul li {
min-width: 0!important;
}
.navigationSlider .slidingNav ul li a {
padding-right: 30px!important;
}
.navigationSlider .slidingNav ul li:nth-child(3) {
display: none;
}
}
@@ -555,8 +564,7 @@ li.navSearchWrapper.reactNavSearchWrapper {
margin-top: 0;
}
ul,
ol {
header ul, ol {
margin-bottom: 0;
}
@@ -640,3 +648,7 @@ input#search_input_react:focus, input#search_input_react:active {
input#search_input_react::placeholder {
color: #cccccc;
}
img#tutorial-todo-create {
width: 600px;
}

View File

@@ -1,6 +1,12 @@
// Copyright 2019-present Facebook Inc. All rights reserved.
// This source code is licensed under the Apache 2.0 license found
// in the LICENSE file in the root directory of this source tree.
/**
* Copyright 2019-present Facebook Inc. All rights reserved.
*
* This source code is licensed under the Apache 2.0 license found
* in the LICENSE file in the root directory of this source tree.
*
* @format
*/
/* eslint-disable */
window.addEventListener('load', function() {