@blockly/field-multilineinput 6.0.5 → 6.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +89 -9
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,6 +1,21 @@
1
1
  # @blockly/field-multilineinput [![Built on Blockly](https://tinyurl.com/built-on-blockly)](https://github.com/google/blockly)
2
2
 
3
- A [Blockly](https://www.npmjs.com/package/blockly) multilineinput field and associated block.
3
+ A [Blockly](https://www.npmjs.com/package/blockly) multiline input field and
4
+ associated block.
5
+
6
+ #### Multiline input field
7
+
8
+ ![A block with the label "multiline text input:" and a multiline input field
9
+ with the text "default text \n with newline character.](readme-media/on_block.png)
10
+
11
+ #### Multiline input field with editor open
12
+
13
+ ![The same block with editor open.](readme-media/with_editor.png)
14
+
15
+ #### Multiline input on collapsed block
16
+
17
+ ![The same block after being collapsed. It has the label "multiline text input:
18
+ defau..." and a jagged right edge to show it is collapsed.](readme-media/collapsed.png)
4
19
 
5
20
  ## Installation
6
21
 
@@ -18,17 +33,23 @@ npm install @blockly/field-multilineinput --save
18
33
 
19
34
  ## Usage
20
35
 
21
- ### Field
36
+ This plugin adds a field of type `FieldMultilineInput` that is registered with
37
+ the name `'field_multilinetext'`. It is a subclass of `Blockly.FieldInput`.
22
38
 
23
- This field accepts up to 3 parameters:
39
+ This field stores a string as its value and a string as its text. Its value is
40
+ always a valid string, while its text could be any string entered into its
41
+ editor. Unlike a text input field, this field also supports newline characters
42
+ entered in the editor.
24
43
 
25
- - "text" to specify the default text. Defaults to `""`.
26
- - "maxLines" to specify the maximum number of lines displayed before scrolling
27
- functionality is enabled. Defaults to `Infinity`.
28
- - "spellcheck" to specify whether spell checking is enabled. Defaults to
29
- `true`.
44
+ The constructor for this field accepts three optional parameters:
30
45
 
31
- The multiline input field is a subclass of Blockly.FieldInput
46
+ - `value`: The default text. Defaults to `""`.
47
+ - `validator`: A function that is called to validate what the user entered.
48
+ - `config`: An object with three optional properties:
49
+ - `maxLines`: The maximum number of lines displayed before scrolling
50
+ functionality is enabled. Defaults to `Infinity`.
51
+ - `spellcheck`: Whether spell checking is enabled. Defaults to `true`.
52
+ - `tooltip`: A tooltip.
32
53
 
33
54
  If you want to use only the field, you must register it with Blockly. You can
34
55
  do this by calling `registerFieldMultilineInput` before instantiating your
@@ -74,6 +95,65 @@ Blockly.defineBlocksWithJsonArray([
74
95
  }]);
75
96
  ```
76
97
 
98
+ ### Customization
99
+
100
+ #### Spellcheck
101
+
102
+ The `setSpellcheck` function can be used to set whether the field spellchecks
103
+ its input text or not. Spellchecking is on by default.
104
+
105
+ ![An animation showing multiline text input fields with and without
106
+ spellcheck.](readme-media/spellcheck.gif)
107
+
108
+ This applies to individual fields. If you want to modify all fields change the
109
+ `Blockly.FieldMultilineInput.prototype.spellcheck_` property.
110
+
111
+ #### Validation
112
+
113
+ A multiline text input field's value is a string, so any validators must accept
114
+ a string and return a string, `null`, or `undefined`.
115
+
116
+ Here is an example of a validator that removes all 'a' characters from the
117
+ string:
118
+
119
+ ```
120
+ function(newValue) {
121
+ return newValue.replace(/a/gm, '');
122
+ }
123
+ ```
124
+
125
+ ![An animation showing validation.](readme-media/validator.gif)
126
+
127
+ ### Serialization
128
+
129
+ #### JSON
130
+
131
+ The JSON for a multiline text input field looks like so:
132
+
133
+ ```json
134
+ {
135
+ "fields": {
136
+ "FIELDNAME": "line1\nline2"
137
+ }
138
+ }
139
+ ```
140
+
141
+ where `FIELDNAME` is a string referencing a multiline text input field, and the
142
+ value is the value to apply to the field. The value follows the same rules as
143
+ the constructor value.
144
+
145
+ #### XML
146
+
147
+ The XML for a multiline text input field looks like so:
148
+
149
+ ```xml
150
+ <field name="FIELDNAME">line1&amp;#10;line2</field>
151
+ ```
152
+
153
+ where the field's `name` attribute contains a string referencing a multiline
154
+ text input field, and the inner text is the value to apply to the field. The
155
+ inner text value follows the same rules as the constructor value.
156
+
77
157
  ### Blocks
78
158
 
79
159
  This package also provides a simple block containing a multiline input
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockly/field-multilineinput",
3
- "version": "6.0.5",
3
+ "version": "6.0.7",
4
4
  "description": "A Blockly multilineinput field.",
5
5
  "scripts": {
6
6
  "audit:fix": "blockly-scripts auditFix",
@@ -21,13 +21,13 @@
21
21
  "field",
22
22
  "multilineinput"
23
23
  ],
24
- "homepage": "https://github.com/google/blockly-samples/tree/master/plugins/field-multilineinput#readme",
24
+ "homepage": "https://github.com/RaspberryPiFoundation/blockly-samples/tree/master/plugins/field-multilineinput#readme",
25
25
  "bugs": {
26
- "url": "https://github.com/google/blockly-samples/issues"
26
+ "url": "https://github.com/RaspberryPiFoundation/blockly-samples/issues"
27
27
  },
28
28
  "repository": {
29
29
  "type": "git",
30
- "url": "https://github.com/google/blockly-samples.git",
30
+ "url": "https://github.com/RaspberryPiFoundation/blockly-samples.git",
31
31
  "directory": "plugins/field-multilineinput"
32
32
  },
33
33
  "license": "Apache-2.0",
@@ -40,8 +40,8 @@
40
40
  "src"
41
41
  ],
42
42
  "devDependencies": {
43
- "@blockly/dev-scripts": "^4.0.10",
44
- "@blockly/dev-tools": "^9.0.5",
43
+ "@blockly/dev-scripts": "^4.0.11",
44
+ "@blockly/dev-tools": "^9.0.7",
45
45
  "chai": "^4.2.0",
46
46
  "sinon": "^9.0.1",
47
47
  "typescript": "^5.4.5"
@@ -55,5 +55,5 @@
55
55
  "engines": {
56
56
  "node": ">=8.0.0"
57
57
  },
58
- "gitHead": "cbfb41d834ede203d6205049f7494bb4a5880859"
58
+ "gitHead": "a2e62db64cb768723367d92034b51ad730ec8c72"
59
59
  }