From 2bc511a021555755c6c23d37100e7a0fa2e3ecbe Mon Sep 17 00:00:00 2001 From: Oliver Drotbohm Date: Thu, 27 Jun 2019 13:31:47 +0200 Subject: [PATCH] #1005 - Polishing. Extended internationalization examples to show sample documents created. Minor polishing. --- .../mediatype/hal/forms/hal-forms-sample.json | 2 - src/main/asciidoc/fundamentals.adoc | 2 +- src/main/asciidoc/mediatypes.adoc | 84 +++++++++++++++---- 3 files changed, 67 insertions(+), 21 deletions(-) diff --git a/src/docs/resources/org/springframework/hateoas/docs/mediatype/hal/forms/hal-forms-sample.json b/src/docs/resources/org/springframework/hateoas/docs/mediatype/hal/forms/hal-forms-sample.json index ca352158..1b149d60 100644 --- a/src/docs/resources/org/springframework/hateoas/docs/mediatype/hal/forms/hal-forms-sample.json +++ b/src/docs/resources/org/springframework/hateoas/docs/mediatype/hal/forms/hal-forms-sample.json @@ -9,7 +9,6 @@ }, "_templates" : { "default" : { - "title" : null, "method" : "put", "contentType" : "", "properties" : [ { @@ -24,7 +23,6 @@ } ] }, "partiallyUpdateEmployee" : { - "title" : null, "method" : "patch", "contentType" : "", "properties" : [ { diff --git a/src/main/asciidoc/fundamentals.adoc b/src/main/asciidoc/fundamentals.adoc index f767b81a..ed6ba875 100644 --- a/src/main/asciidoc/fundamentals.adoc +++ b/src/main/asciidoc/fundamentals.adoc @@ -305,4 +305,4 @@ By trading in domain knowledge and instead adding protocol support for HAL-FORMS to server-side changes. No need to update your client every time a domain change is made on the server. IMPORTANT: HAL-FORMS only supports affordances against the `self` link, but other affordance-aware media types may not -have the same restriction. In general, don't define affordances based on one particular media type. \ No newline at end of file +have the same restriction. In general, don't define affordances based on one particular media type. diff --git a/src/main/asciidoc/mediatypes.adoc b/src/main/asciidoc/mediatypes.adoc index ae03b4c1..8fa6b882 100644 --- a/src/main/asciidoc/mediatypes.adoc +++ b/src/main/asciidoc/mediatypes.adoc @@ -110,6 +110,27 @@ _links.payment.title=Proceed to checkout ---- ==== +This will result in the following HAL representation: + +.A sample HAL document with link titles defined +==== +[source, javascript] +---- +{ + "_links" : { + "cancel" : { + "href" : "…" + "title" : "Cancel order" + }, + "payment" : { + "href" : "…" + "title" : "Proceed to checkout" + } + } +} +---- +==== + [[mediatypes.hal.curie-provider]] === [[spis.curie-provider]] Using the `CurieProvider` API @@ -190,22 +211,21 @@ HAL-FORMS contains attributes that are intended for human interpretation, like a These can be defined and internationalized using Spring's resource bundle support and the `rest-messages` resource bundle configured by Spring HATEOAS by default. ==== Template titles -To define a template title use the following pattern: `_template.$affordanceName.title`. Note, that in HAL-FORMS, the name of a template is `default` if it is the only one. +To define a template title use the following pattern: `_templates.$affordanceName.title`. Note, that in HAL-FORMS, the name of a template is `default` if it is the only one. This means that you'll usually have to qualify the key with the local or fully qualified input type name that affordance describes. .Defining HAL-FORMS template titles ==== [source] ---- -_template.default.title=Some title <1> -_template.postOrder.title=Create order <2> -Order._template.default.title=Create order <3> -com.acme.order.Order._template.default.title=Create order <4> - +_templates.default.title=Some title <1> +_templates.putEmployee.title=Create employee <2> +Employee._templates.default.title=Create employee <3> +com.acme.Employee._templates.default.title=Create employee <4> ---- <1> A global definition for the title using `default` as key. <2> A global definition for the title using the actual affordance name as key. Unless defined explicitly when creating the affordance, this defaults to `$httpMethod + $simpleInputTypeName`. -<3> A locally defined title to be applied to all types named `Order`. +<3> A locally defined title to be applied to all types named `Employee`. <4> A title definition using the fully-qualified type name. ==== @@ -219,15 +239,46 @@ The keys can be defined globally, locally or fully-qualified and need an `._prom ==== [source] ---- -email._prompt=Email address <1> -Customer.email_prompt=Email address <2> -com.acme.Customer.email._prompt <3> +firstName._prompt=Firstname <1> +Employee.firstName=Firstname <2> +com.acme.Employee.firstName._prompt=Firstname <3> ---- -<1> All properties named `email` will get "Email address" rendered, independent of the type they're declared in. -<2> Properties in types named `Customer` will be prompted "Email address". -<3> The `email` property of `com.acme.Customer` will get a prompt of "Email address" assigned. +<1> All properties named `email` will get "Firstname" rendered, independent of the type they're declared in. +<2> The `firstName` property in types named `Employee` will be prompted "Firstname". +<3> The `firstName` property of `com.acme.Employee` will get a prompt of "Firstname" assigned. ==== +A sample document with both template titles and property prompts defined would then look something like this: + +.A sample HAL-FORMS document with internationalized template titles and property prompts +==== +[source] +---- +{ + …, + "_templates" : { + "default" : { + "title" : "Create employee", + "method" : "put", + "contentType" : "", + "properties" : [ { + "name" : "firstName", + "prompt" : "Firstname", + "required" : true + }, { + "name" : "lastName", + "prompt" : "Lastname", + "required" : true + }, { + "name" : "role", + "prompt" : "Role", + "required" : true + } ] + } + } +} +---- +==== [[mediatypes.collection-json]] == Collection+JSON @@ -241,7 +292,6 @@ management and querying of simple collections. ____ Collection+JSON provides a uniform way to represent both single item resources as well as collections. - To enable this media type, put the following configuration in your code: .Collection+JSON enabled application @@ -301,9 +351,7 @@ The UBER document format is a minimal read/write hypermedia type designed to sup hypermedia-based transitions. ____ -UBER provides a uniform way to represent both single item resources as well as collections. - -To enable this media type, put the following configuration in your code: +UBER provides a uniform way to represent both single item resources as well as collections. To enable this media type, put the following configuration in your code: .UBER+JSON enabled application ==== @@ -356,7 +404,7 @@ That implementation class could then look as follows: .An example `MediaTypeConfigurationProvider` implementation in `META-INF/spring.factories` ==== -[source,java] +[source, java] ---- class MyMediaTypeConfigurationProvider implements MediaTypeConfigurationProvider {