From c81fe374bdb9c759a567fd6558b2ed63cf92663e Mon Sep 17 00:00:00 2001 From: Ronald Bourret Date: Mon, 29 Dec 2025 23:05:09 +0000 Subject: [PATCH 1/3] fix: Update multiline text readme to include the information currently on devsite --- plugins/field-multilineinput/README.md | 122 ++++++++++++++++++++----- 1 file changed, 101 insertions(+), 21 deletions(-) diff --git a/plugins/field-multilineinput/README.md b/plugins/field-multilineinput/README.md index 8190427012..97a847f214 100644 --- a/plugins/field-multilineinput/README.md +++ b/plugins/field-multilineinput/README.md @@ -1,6 +1,21 @@ # @blockly/field-multilineinput [![Built on Blockly](https://tinyurl.com/built-on-blockly)](https://github.com/google/blockly) -A [Blockly](https://www.npmjs.com/package/blockly) multilineinput field and associated block. +A [Blockly](https://www.npmjs.com/package/blockly) multiline input field and + associated block. + +#### Multiline input field + +![A block with the label "multiline text input:" and a multiline input field +with the text "default text \n with newline character.](readme-media/on_block.png) + +#### Multiline input field with editor open + +![The same block with editor open.](readme-media/with_editor.png) + +#### Multiline input on collapsed block + +![The same block after being collapsed. It has the label "multiline text input: +defau..." and a jagged right edge to show it is collapsed.](readme-media/collapsed.png) ## Installation @@ -18,17 +33,23 @@ npm install @blockly/field-multilineinput --save ## Usage -### Field +This plugin adds a field of type `FieldMultilineInput` that is registered with +the name `'field_multilinetext'`. It is a subclass of `Blockly.FieldInput`. -This field accepts up to 3 parameters: +This field stores a string as its value and a string as its text. Its value is +always a valid string, while its text could be any string entered into its +editor. Unlike a text input field, this field also supports newline characters +entered in the editor. -- "text" to specify the default text. Defaults to `""`. -- "maxLines" to specify the maximum number of lines displayed before scrolling - functionality is enabled. Defaults to `Infinity`. -- "spellcheck" to specify whether spell checking is enabled. Defaults to - `true`. +The constructor for this field accepts three optional parameters: -The multiline input field is a subclass of Blockly.FieldInput +- `value`: The default text. Defaults to `""`. +- `validator`: A function that is called to validate what the user entered. +- `config`: An object with three optional properties: + - `maxLines`: The maximum number of lines displayed before scrolling + functionality is enabled. Defaults to `Infinity`. + - `spellcheck`: Whether spell checking is enabled. Defaults to `true`. + - `tooltip`: A tooltip. If you want to use only the field, you must register it with Blockly. You can do this by calling `registerFieldMultilineInput` before instantiating your @@ -38,17 +59,17 @@ overwrite it. ### JavaScript ```js -import * as Blockly from 'blockly'; -import {registerFieldMultilineInput} from '@blockly/field-multilineinput'; +import * as Blockly from "blockly"; +import { registerFieldMultilineInput } from "@blockly/field-multilineinput"; registerFieldMultilineInput(); -Blockly.Blocks['test_field_multilineinput'] = { +Blockly.Blocks["test_field_multilineinput"] = { init: function () { this.appendDummyInput() - .appendField('multilineinput: ') + .appendField("multilineinput: ") .appendField( - new FieldMultilineInput('some text \n with newlines'), - 'FIELDNAME', + new FieldMultilineInput("some text \n with newlines"), + "FIELDNAME", ); }, }; @@ -74,6 +95,65 @@ Blockly.defineBlocksWithJsonArray([ }]); ``` +### Customization + +#### Spellcheck + +The `setSpellcheck` function can be used to set whether the field spellchecks +its input text or not. Spellchecking is on by default. + +![An animation showing multiline text input fields with and without +spellcheck.](readme-media/spellcheck.gif) + +This applies to individual fields. If you want to modify all fields change the +`Blockly.FieldMultilineInput.prototype.spellcheck_` property. + +#### Validation + +A multiline text input field's value is a string, so any validators must accept +a string and return a string, `null`, or `undefined`. + +Here is an example of a validator that removes all 'a' characters from the +string: + +``` +function(newValue) { + return newValue.replace(/a/gm, ''); +} +``` + +![An animation showing validation.](readme-media/validator.gif) + +### Serialization + +#### JSON + +The JSON for a multiline text input field looks like so: + +```json +{ + "fields": { + "FIELDNAME": "line1\nline2" + } +} +``` + +where `FIELDNAME` is a string referencing a multiline text input field, and the +value is the value to apply to the field. The value follows the same rules as +the constructor value. + +#### XML + +The XML for a multiline text input field looks like so: + +```xml +line1
line2 +``` + +where the field's `name` attribute contains a string referencing a multiline +text input field, and the inner text is the value to apply to the field. The +inner text value follows the same rules as the constructor value. + ### Blocks This package also provides a simple block containing a multiline input @@ -87,12 +167,12 @@ function will also install the correct generator function for the corresponding language(s). ```js -import {javascriptGenerator} from 'blockly/javascript'; -import {dartGenerator} from 'blockly/dart'; -import {phpGenerator} from 'blockly/php'; -import {pythonGenerator} from 'blockly/python'; -import {luaGenerator} from 'blockly/lua'; -import {textMultiline} from '@blockly/field-multilineinput'; +import { javascriptGenerator } from "blockly/javascript"; +import { dartGenerator } from "blockly/dart"; +import { phpGenerator } from "blockly/php"; +import { pythonGenerator } from "blockly/python"; +import { luaGenerator } from "blockly/lua"; +import { textMultiline } from "@blockly/field-multilineinput"; // Installs the block, the field, and all of the language generators. textMultiline.installBlock({ From cb34132815b90b3fde9c8439a0f5a7fe1c166c86 Mon Sep 17 00:00:00 2001 From: Ronald Bourret Date: Mon, 29 Dec 2025 23:27:43 +0000 Subject: [PATCH 2/3] chore: Run Prettier --- plugins/field-multilineinput/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/field-multilineinput/README.md b/plugins/field-multilineinput/README.md index 97a847f214..61d7b5d994 100644 --- a/plugins/field-multilineinput/README.md +++ b/plugins/field-multilineinput/README.md @@ -1,7 +1,7 @@ # @blockly/field-multilineinput [![Built on Blockly](https://tinyurl.com/built-on-blockly)](https://github.com/google/blockly) A [Blockly](https://www.npmjs.com/package/blockly) multiline input field and - associated block. +associated block. #### Multiline input field From 277667e28b3503401952e8e21b2aa4cd2f8f991f Mon Sep 17 00:00:00 2001 From: Ronald Bourret Date: Tue, 30 Dec 2025 16:31:38 +0000 Subject: [PATCH 3/3] fix: Run Prettier again --- plugins/field-multilineinput/README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/plugins/field-multilineinput/README.md b/plugins/field-multilineinput/README.md index 61d7b5d994..5716581e6b 100644 --- a/plugins/field-multilineinput/README.md +++ b/plugins/field-multilineinput/README.md @@ -59,17 +59,17 @@ overwrite it. ### JavaScript ```js -import * as Blockly from "blockly"; -import { registerFieldMultilineInput } from "@blockly/field-multilineinput"; +import * as Blockly from 'blockly'; +import {registerFieldMultilineInput} from '@blockly/field-multilineinput'; registerFieldMultilineInput(); -Blockly.Blocks["test_field_multilineinput"] = { +Blockly.Blocks['test_field_multilineinput'] = { init: function () { this.appendDummyInput() - .appendField("multilineinput: ") + .appendField('multilineinput: ') .appendField( - new FieldMultilineInput("some text \n with newlines"), - "FIELDNAME", + new FieldMultilineInput('some text \n with newlines'), + 'FIELDNAME', ); }, }; @@ -167,12 +167,12 @@ function will also install the correct generator function for the corresponding language(s). ```js -import { javascriptGenerator } from "blockly/javascript"; -import { dartGenerator } from "blockly/dart"; -import { phpGenerator } from "blockly/php"; -import { pythonGenerator } from "blockly/python"; -import { luaGenerator } from "blockly/lua"; -import { textMultiline } from "@blockly/field-multilineinput"; +import {javascriptGenerator} from 'blockly/javascript'; +import {dartGenerator} from 'blockly/dart'; +import {phpGenerator} from 'blockly/php'; +import {pythonGenerator} from 'blockly/python'; +import {luaGenerator} from 'blockly/lua'; +import {textMultiline} from '@blockly/field-multilineinput'; // Installs the block, the field, and all of the language generators. textMultiline.installBlock({