Basic form docs #1228

andresmgot · 2019-10-16T14:14:38Z

absoludity

Great stuff! A couple of wording thoughts but feel free to ignore as you like. One question about allowing defaults even though they can be specified in the values, that I'm keen to understand.

absoludity · 2019-10-16T23:10:30Z

docs/developer/basic-form-support.md

+
+**NOTE:** This feature is under heavy development. Some of the described below may change in the future.
+
+Since Kubeapps 1.6.0, it's possible to attach a chart with a JSON schema that defines the structure of the `values.yaml` file. This JSON schema is used with two goals:


s/attach/include/

absoludity · 2019-10-16T23:11:01Z

docs/developer/basic-form-support.md

+
+Since Kubeapps 1.6.0, it's possible to attach a chart with a JSON schema that defines the structure of the `values.yaml` file. This JSON schema is used with two goals:
+
+ - Validate that the given values satisfy the schema defined. In case the submitted values are not valid, the installation or upgrade will fail.


Might be worth mentioning that this is actually the helm 3 use-case.

absoludity · 2019-10-16T23:11:50Z

docs/developer/basic-form-support.md

+Since Kubeapps 1.6.0, it's possible to attach a chart with a JSON schema that defines the structure of the `values.yaml` file. This JSON schema is used with two goals:
+
+ - Validate that the given values satisfy the schema defined. In case the submitted values are not valid, the installation or upgrade will fail.
+ - Present the user with a simple (basic) form so the chart is easier to deploy and configure.


"with a simpler form" rather than "with a simple (basic) form"

absoludity · 2019-10-16T23:14:19Z

docs/developer/basic-form-support.md

+ - Validate that the given values satisfy the schema defined. In case the submitted values are not valid, the installation or upgrade will fail.
+ - Present the user with a simple (basic) form so the chart is easier to deploy and configure.
+
+The goal of the basic form is to define the most common parameters that users typically modify before deploying a chart (like username and password) so they are able to modify them with a more user-friendly form.


The form itself isn't defining the most common properties - the schema is, right? So perhaps, "The goal of this feature is to present the user with the most common parameters which are typically modified before deploying a chart (like username and password) in a more user-friendly form."

absoludity · 2019-10-16T23:15:29Z

docs/developer/basic-form-support.md

+
+## Additional annotations used to identify basic parameters
+
+In order to identify, among all the values specified in the schema, the values that should be presented in the form, it's necessary to include some special tags.


Simpler: In order to identify which values should be presented in the form, ...

absoludity · 2019-10-16T23:16:38Z

docs/developer/basic-form-support.md

+
+In order to identify, among all the values specified in the schema, the values that should be presented in the form, it's necessary to include some special tags.
+
+First of all, it's necessary to specify the tag `form`. This field should be unique and it should identify the parameter. All the properties marked with this key in the schema will be represented in the form. For example:


s/This field/The value of the form tag/ (and standardise on either field or tag or key)

absoludity · 2019-10-16T23:19:00Z

docs/developer/basic-form-support.md

+    },
+```
+
+With the definition above, we are marking the value `wordpressUsername` as a value to be represented in the form (with the ID `username`). Note that we are also specifying the `type` that will be used to render the proper HTML components to represent the input in the form:


Isn't type part of the jsonschema, and it's also being used here to render? In which case "Note that the type is also used to render..." (the current sentence implies that we're only specifying it for the rendering, rather than because it's part of the schema).

okay, yes, it's used for both

absoludity · 2019-10-16T23:21:40Z

docs/developer/basic-form-support.md

+
+In addition to the `type`, there are other tags that can be used to customize the way the parameter is represented:
+
+ - `title` is used to render the title of the parameter. If it's not specified, Kubeapps will use the ID of the component.


"Kubeapps will use the ID of the component (ie. the value of the form field)." (it wasn't 100% clear, but I see now that's what you're referring to).

absoludity · 2019-10-16T23:23:26Z

docs/developer/basic-form-support.md

+
+ - `title` is used to render the title of the parameter. If it's not specified, Kubeapps will use the ID of the component.
+ - `description` is used to include additional information of the parameter.
+ - `default` is used to set a default value. If it's not set, the default value from the `values.yaml` file will be used.


Oh ... not sure that's a good idea? Why have two places to specify a default, so that you'll get different defaults depending on what UI you use? What is the reason for having a second default here rather than just using the one from the values.yaml always?

sorry, I expressed it the other way. If the value is set in the values.yaml it will always be used as the default. In case that is not set and the default value is set in the schema, that one will be used.

Yeah, but is there any reason to enable setting a default in the schema for a field at all, given the right place for that is already in the values.yaml? If not, I'd personally update this sentence removing any mention of default (or just saying the default is set in the values) and later remove support for a separate default in the schema. +1 either way, but I'm keen to know if there's a need at all for a second way to set the default for a field.

andresmgot

Thank you for the review!

andresmgot · 2019-10-17T10:01:38Z

docs/developer/basic-form-support.md

+    },
+```
+
+With the definition above, we are marking the value `wordpressUsername` as a value to be represented in the form (with the ID `username`). Note that we are also specifying the `type` that will be used to render the proper HTML components to represent the input in the form:


okay, yes, it's used for both

andresmgot · 2019-10-17T10:09:50Z

docs/developer/basic-form-support.md

+
+ - `title` is used to render the title of the parameter. If it's not specified, Kubeapps will use the ID of the component.
+ - `description` is used to include additional information of the parameter.
+ - `default` is used to set a default value. If it's not set, the default value from the `values.yaml` file will be used.


sorry, I expressed it the other way. If the value is set in the values.yaml it will always be used as the default. In case that is not set and the default value is set in the schema, that one will be used.

Basic form docs

c615011

absoludity reviewed Oct 16, 2019

View reviewed changes

andresmgot commented Oct 17, 2019

View reviewed changes

Apply review feedback

0f9f95f

absoludity approved these changes Oct 17, 2019

View reviewed changes

Merge branch 'master' into docs

2c2cd98

andresmgot merged commit 939959f into vmware-tanzu:master Oct 17, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Basic form docs #1228

Basic form docs #1228

andresmgot commented Oct 16, 2019

absoludity left a comment

absoludity Oct 16, 2019

absoludity Oct 16, 2019

absoludity Oct 16, 2019

absoludity Oct 16, 2019

absoludity Oct 16, 2019

absoludity Oct 16, 2019

absoludity Oct 16, 2019

andresmgot Oct 17, 2019

absoludity Oct 16, 2019

absoludity Oct 16, 2019

andresmgot Oct 17, 2019

absoludity Oct 17, 2019

andresmgot left a comment

andresmgot Oct 17, 2019

andresmgot Oct 17, 2019


		NOTE: This feature is under heavy development. Some of the described below may change in the future.

		Since Kubeapps 1.6.0, it's possible to attach a chart with a JSON schema that defines the structure of the `values.yaml` file. This JSON schema is used with two goals:


		Since Kubeapps 1.6.0, it's possible to attach a chart with a JSON schema that defines the structure of the `values.yaml` file. This JSON schema is used with two goals:

		- Validate that the given values satisfy the schema defined. In case the submitted values are not valid, the installation or upgrade will fail.


		## Additional annotations used to identify basic parameters

		In order to identify, among all the values specified in the schema, the values that should be presented in the form, it's necessary to include some special tags.


		In order to identify, among all the values specified in the schema, the values that should be presented in the form, it's necessary to include some special tags.

		First of all, it's necessary to specify the tag `form`. This field should be unique and it should identify the parameter. All the properties marked with this key in the schema will be represented in the form. For example:


		In addition to the `type`, there are other tags that can be used to customize the way the parameter is represented:

		- `title` is used to render the title of the parameter. If it's not specified, Kubeapps will use the ID of the component.

Basic form docs #1228

Basic form docs #1228

Conversation

andresmgot commented Oct 16, 2019

absoludity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andresmgot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment