Skip to content

Commit

Permalink
Use ExampleTabs where they weren't used previously (#3538)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tobias-tengler
tobias-tengler authored Apr 22, 2021
1 parent 4b9be94 commit bbdfe71
Show file tree
Hide file tree
Showing 6 changed files with 378 additions and 317 deletions.
48 changes: 26 additions & 22 deletions website/src/docs/hotchocolate/api-reference/object-type.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,55 +156,59 @@ The GraphQL SDL supports extending object types, this means that we can add fiel

Extending types is useful for schema stitching but also when we want to add just something to an exist type or if we just want to split large type definitions. The latter is often the case with the query type definition.

Hot Chocolate supports extending types with SDL-first, code-first with annotations and code-first with fluent. Let\`s have a look at how we can extend our person object:

SDL-First:

```sdl
extend type Person {
address: String!
}
```

Code-First annotation-based:
<ExampleTabs>
<ExampleTabs.Annotation>

```csharp
[ExtendObjectType(Name = "Person")]
[ExtendObjectType("Person")]
public class PersonResolvers
{
public IEnumerable<Person> GetFriends([Parent]Person person, [Service]IPersonRepository repository) =>
repository.GetFriends(person.Id);
public IEnumerable<Person> GetFriends([Parent] Person person, [Service] IPersonRepository repository)
=> repository.GetFriends(person.Id);
}

services
.AddGraphQLServer()
...
.AddType<PersonType>()
// ...
.AddType<PersonResolvers>();
```

Code-First
</ExampleTabs.Annotation>
<ExampleTabs.Code>

```csharp
public class PersonTypeExtension
: ObjectTypeExtension
public class PersonTypeExtension : ObjectTypeExtension
{
protected override void Configure(IObjectTypeDescriptor descriptor)
{
descriptor.Name("Person");
descriptor.Field("address")
.Type<NonNullType<StringType>>()
.Resolver(/"Resolver Logic"/);
.Resolver(context =>
{
// resolver logic
});
}
}

services
.AddGraphQLServer()
...
.AddType<PersonType>()
// ...
.AddType<PersonTypeExtension>()
```

</ExampleTabs.Code>
<ExampleTabs.Schema>

```sdl
extend type Person {
address: String!
}
```

</ExampleTabs.Schema>
</ExampleTabs>

Type extensions basically work like usual types and are also added like usual types.

More about type extensions can be found [here](../defining-a-schema/extending-types).
109 changes: 63 additions & 46 deletions website/src/docs/hotchocolate/defining-a-schema/scalars.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
title: "Scalars"
---

import { ExampleTabs } from "../../../components/mdx/example-tabs"

A GraphQL schema should be built as expressive as possible.
Just from looking at the schema, a developer should know how to use the API.
In GraphQL you are not limited to only describing the structure of a type, you can even describe value types.
Expand Down Expand Up @@ -39,9 +41,10 @@ In addition to the scalars defined by the specification, HotChocolate also suppo
| `Any` | This type can be anything, string, int, list or object etc. |

# Using Scalars

HotChocolate will automatically detect which scalars are in use and will only expose those in the introspection. This keeps the schema definition small, simple and clean.

The schema discovers .NET types and binds the matching scalar to the type.
The schema discovers .NET types and binds the matching scalar to the type.
HotChocolate, for example, automatically binds the `StringType` on a member of the type `System.String`.
You can override these mappings by explicitly specifying type bindings on the request executor builder.

Expand Down Expand Up @@ -94,7 +97,7 @@ services

# Any Type

The `Any` scalar is a special type that can be compared to `object` in C#.
The `Any` scalar is a special type that can be compared to `object` in C#.
`Any` allows us to specify any literal or return any output type.

Consider the following type:
Expand Down Expand Up @@ -154,21 +157,24 @@ If you want to access an object dynamically without serializing it to a strongly
Lists can be accessed generically by getting them as `IReadOnlyList<object>` or as `ListValueNode`.

# Custom Converter

HotChocolate converts .Net types to match the types supported by the scalar of the field.
By default, all standard .Net types have converters registered.
By default, all standard .Net types have converters registered.
You can register converters and reuse the built-in scalar types.
In case you use a non-standard library, e.g. [Noda Time](https://nodatime.org/), you can register a converter and use the standard `DateTimeType`.

```csharp
public class Query
public class Query
{
public OffsetDateTime GetDateTime(OffsetDateTime offsetDateTime)
{
return offsetDateTime;
}
}
```
*Startup*

_Startup_

```csharp
public void ConfigureServices(IServiceCollection services)
{
Expand Down Expand Up @@ -348,29 +354,34 @@ By extending `ScalarType` you have full control over serialization and parsing.
```

# Additional Scalars
HotChocolate provides additional scalars for more specific usecases.

HotChocolate provides additional scalars for more specific usecases.

To use these scalars you have to add the package `HotChocolate.Types.Scalars`

```csharp
dotnet add package HotChocolate.Types.Scalars
```

These scalars cannot be mapped by HotChocolate to a field.
These scalars cannot be mapped by HotChocolate to a field.
You need to specify them manually.

**Annotation Based**
<ExampleTabs>
<ExampleTabs.Annotation>

```csharp
public class User
public class User
{
[GraphQLType(typeof(NonEmptyStringType))]
public string UserName { get; set; }
}
```

**Code First**
</ExampleTabs.Annotation>
<ExampleTabs.Code>

```csharp
public class UserType : ObjectType<User>
public class UserType : ObjectType<User>
{
protected override void Configure(
IObjectTypeDescriptor<User> descriptor)
Expand All @@ -380,49 +391,55 @@ public class UserType : ObjectType<User>
}
```

**Schema First**
```sql
</ExampleTabs.Code>
<ExampleTabs.Schema>

```sdl
type User {
userName: NonEmptyString
}
```

You will also have to add the Scalar to the schema:
</ExampleTabs.Schema>
</ExampleTabs>

You will also have to add the Scalar to the schema:

```csharp
services
.AddGraphQLServer()
// ....
.AddType<NonEmptyStringType>()
.AddGraphQLServer()
// ....
.AddType<NonEmptyStringType>()
```

**Available Scalars:**

| Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| EmailAddress | The `EmailAddress` scalar type represents a email address, represented as UTF-8 character sequences that follows the specification defined in RFC 5322.
| HexColor | The `HexColor` scalar type represents a valid HEX color code.
| Hsl | The `Hsl` scalar type represents a valid a CSS HSL color as defined here https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#hsl_colors.
| Hsla | The `Hsla` scalar type represents a valid a CSS HSLA color as defined here https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#hsl_colors.
| IPv4 | The `IPv4` scalar type represents a valid a IPv4 address as defined here https://en.wikipedia.org/wiki/IPv4.
| IPv6 | The `IPv6` scalar type represents a valid a IPv6 address as defined here [RFC8064](https://tools.ietf.org/html/rfc8064).
| Isbn | The `ISBN` scalar type is a ISBN-10 or ISBN-13 number: https:\/\/en.wikipedia.org\/wiki\/International_Standard_Book_Number.
| LocalCurrency | The `LocalCurrency` scalar type is a currency string.
| LocalDate | The `LocalDate` scalar type represents a ISO date string, represented as UTF-8 character sequences yyyy-mm-dd. The scalar follows the specification defined in RFC3339.
| LocalTime | The `LocalTime` scalar type is a local time string (i.e., with no associated timezone) in 24-hr `HH:mm:ss]`.
| MacAddress | The `MacAddess` scalar type represents a IEEE 802 48-bit Mac address, represented as UTF-8 character sequences. The scalar follows the specification defined in [RFC7042](https://tools.ietf.org/html/rfc7042#page-19).
| NegativeFloat | The `NegativeFloat` scalar type represents a double‐precision fractional value less than 0.
| NegativeInt | The `NegativeIntType` scalar type represents a signed 32-bit numeric non-fractional with a maximum of -1.
| NonEmptyString | The `NonNullString` scalar type represents non empty textual data, represented as UTF‐8 character sequences with at least one character.
| NonNegativeFloat | The `NonNegativeFloat` scalar type represents a double‐precision fractional value greater than or equal to 0.
| NonNegativeInt | The `NonNegativeIntType` scalar type represents a unsigned 32-bit numeric non-fractional value greater than or equal to 0.
| NonPositiveFloat | The `NonPositiveFloat` scalar type represents a double‐precision fractional value less than or equal to 0.
| NonPositiveInt | The `NonPositiveInt` scalar type represents a signed 32-bit numeric non-fractional value less than or equal to 0.
| PhoneNumber | The `PhoneNumber` scalar type represents a value that conforms to the standard E.164 format as specified in: https://en.wikipedia.org/wiki/E.164.
| PositiveInt | The `PositiveInt` scalar type represents a signed 32‐bit numeric non‐fractional value of at least the value 1.
| PostalCode | The `PostalCode` scalar type represents a valid postal code.
| Port | The `Port` scalar type represents a field whose value is a valid TCP port within the range of 0 to 65535.
| Rgb | The `RGB` scalar type represents a valid CSS RGB color as defined here [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb()_and_rgba()).
| Rgba | The `RGBA` scalar type represents a valid CSS RGBA color as defined here [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb()_and_rgba()).
| UnsignedInt | The `UnsignedInt` scalar type represents a unsigned 32‐bit numeric non‐fractional value greater than or equal to 0.
| UnsignedLong | The `UnsignedLong` scalar type represents a unsigned 64‐bit numeric non‐fractional value greater than or equal to 0.
| UtcOffset | The `UtcOffset` scalar type represents a value of format `±hh:mm`.
| Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| EmailAddress | The `EmailAddress` scalar type represents a email address, represented as UTF-8 character sequences that follows the specification defined in RFC 5322. |
| HexColor | The `HexColor` scalar type represents a valid HEX color code. |
| Hsl | The `Hsl` scalar type represents a valid a CSS HSL color as defined [here](https://developer.mozilla.org/en-US/docs/Web/CSS/) color_value#hsl_colors. |
| Hsla | The `Hsla` scalar type represents a valid a CSS HSLA color as defined [here](https://developer.mozilla.org/en-US/docs/Web/CSS/) color_value#hsl_colors. |
| IPv4 | The `IPv4` scalar type represents a valid a IPv4 address as defined [here](https://en.wikipedia.org/wiki/) IPv4. |
| IPv6 | The `IPv6` scalar type represents a valid a IPv6 address as defined here [RFC8064](https://tools.ietf.org/html/rfc8064). |
| Isbn | The `ISBN` scalar type is a ISBN-10 or ISBN-13 number: https:\/\/en.wikipedia.org\/wiki\/International_Standard_Book_Number. |
| LocalCurrency | The `LocalCurrency` scalar type is a currency string. |
| LocalDate | The `LocalDate` scalar type represents a ISO date string, represented as UTF-8 character sequences yyyy-mm-dd. The scalar follows the specification defined in RFC3339. |
| LocalTime | The `LocalTime` scalar type is a local time string (i.e., with no associated timezone) in 24-hr `HH:mm:ss]`. |
| MacAddress | The `MacAddess` scalar type represents a IEEE 802 48-bit Mac address, represented as UTF-8 character sequences. The scalar follows the specification defined in [RFC7042](https://tools.ietf.org/html/rfc7042#page-19). |
| NegativeFloat | The `NegativeFloat` scalar type represents a double‐precision fractional value less than 0. |
| NegativeInt | The `NegativeIntType` scalar type represents a signed 32-bit numeric non-fractional with a maximum of -1. |
| NonEmptyString | The `NonNullString` scalar type represents non empty textual data, represented as UTF‐8 character sequences with at least one character. |
| NonNegativeFloat | The `NonNegativeFloat` scalar type represents a double‐precision fractional value greater than or equal to 0. |
| NonNegativeInt | The `NonNegativeIntType` scalar type represents a unsigned 32-bit numeric non-fractional value greater than or equal to 0. |
| NonPositiveFloat | The `NonPositiveFloat` scalar type represents a double‐precision fractional value less than or equal to 0. |
| NonPositiveInt | The `NonPositiveInt` scalar type represents a signed 32-bit numeric non-fractional value less than or equal to 0. |
| PhoneNumber | The `PhoneNumber` scalar type represents a value that conforms to the standard E.164 format as specified [here](https://en.wikipedia.org/wiki/E).164. |
| PositiveInt | The `PositiveInt` scalar type represents a signed 32‐bit numeric non‐fractional value of at least the value 1. |
| PostalCode | The `PostalCode` scalar type represents a valid postal code. |
| Port | The `Port` scalar type represents a field whose value is a valid TCP port within the range of 0 to 65535. |
| Rgb | The `RGB` scalar type represents a valid CSS RGB color as defined [here](<https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb()_and_rgba()>). |
| Rgba | The `RGBA` scalar type represents a valid CSS RGBA color as defined [here](<https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb()_and_rgba()>). |
| UnsignedInt | The `UnsignedInt` scalar type represents a unsigned 32‐bit numeric non‐fractional value greater than or equal to 0. |
| UnsignedLong | The `UnsignedLong` scalar type represents a unsigned 64‐bit numeric non‐fractional value greater than or equal to 0. |
| UtcOffset | The `UtcOffset` scalar type represents a value of format `±hh:mm`. |
Loading

0 comments on commit bbdfe71

Please sign in to comment.