|
| 1 | +--- |
| 2 | +title: Field actions |
| 3 | +slug: content-creation/field-actions |
| 4 | +description: Learn how you can add your custom field actions to populate the field with a specific value. |
| 5 | +date: 2024-08-13T10:03:04.087Z |
| 6 | +lastmod: 2024-08-13T11:11:27.339Z |
| 7 | +weight: 200.52 |
| 8 | +--- |
| 9 | + |
| 10 | +# Field actions |
| 11 | + |
| 12 | +Field actions (`actions` property on the field) can be used to populate a field with a specific value. |
| 13 | +The difference between a field action |
| 14 | +and a placeholder is that the field action needs to be manually triggered by the user. |
| 15 | + |
| 16 | +The field action can be used to populate the field with information coming from a script. |
| 17 | +For example to generate a unique ID. |
| 18 | + |
| 19 | +The following field types support field actions: |
| 20 | + |
| 21 | +- `string`: return a string value |
| 22 | +- `tags`: return an array of strings |
| 23 | +- `categories`: return an array of strings |
| 24 | +- `taxonomy`: return an array of strings |
| 25 | +- `image`: : return a string when single image is used, or an array of strings when multiple images |
| 26 | +are used |
| 27 | + |
| 28 | +## Creating a new script |
| 29 | + |
| 30 | +> **Important**: The field actions scripts make use of the `@frontmatter/extensibility` library. |
| 31 | +> More information to install it can be found in the [Extensibility library][01] section. |
| 32 | +
|
| 33 | +The `@frontmatter/extensibility` package provides you the following arguments for your field action script: |
| 34 | + |
| 35 | +```javascript {{ "title": "Field action script" }} |
| 36 | +import { FieldAction } from '@frontmatter/extensibility'; |
| 37 | + |
| 38 | +(async () => { |
| 39 | + // Retrieve the front matter of the current content |
| 40 | + const { frontMatter } = FieldAction.getArguments(); |
| 41 | + |
| 42 | + // Write your logic here to create the field value |
| 43 | + const value = "Your value here"; |
| 44 | + |
| 45 | + // Update the field with the new value |
| 46 | + FieldAction.update(value); |
| 47 | +})(); |
| 48 | +``` |
| 49 | + |
| 50 | +## Configure the script |
| 51 | + |
| 52 | +The configuration of the field action is done on the content type field configuration. |
| 53 | + |
| 54 | +```json {{ "title": "Field action configuration" }} |
| 55 | +{ |
| 56 | + "frontMatter.taxonomy.contentTypes": [{ |
| 57 | + "name": "sample", |
| 58 | + "fields": [{ |
| 59 | + "title": "Title", |
| 60 | + "name": "title", |
| 61 | + "type": "string", |
| 62 | + "required": true, |
| 63 | + "actions": [{ |
| 64 | + "title": "Update field value", |
| 65 | + "script": "./scripts/field.script.mjs", |
| 66 | + "command": "~/.nvm/versions/node/v20.11.1/bin/node" |
| 67 | + }] |
| 68 | + } |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +> **Info**: You are able to add multiple field actions to a single field. |
| 73 | + |
| 74 | +Once the script has been configured, you can see the script action icon on the field. |
| 75 | + |
| 76 | +- If you have a single field action defined and click the icon, the field action will be executed. |
| 77 | +- If you have multiple field actions defined, a dropdown will be shown with the available field actions. |
| 78 | + |
| 79 | +![Custom field actions][02] |
| 80 | + |
| 81 | +## Sample scripts |
| 82 | + |
| 83 | +### Update title by Ollama AI |
| 84 | + |
| 85 | +The following script will update the title field value with a title generated by the Ollama AI. |
| 86 | + |
| 87 | +```javascript {{ "title": "Update title by Ollama AI" }} |
| 88 | +import { FieldAction } from '@frontmatter/extensibility'; |
| 89 | +import ollama from 'ollama'; |
| 90 | + |
| 91 | +(async () => { |
| 92 | + const { frontMatter } = FieldAction.getArguments(); |
| 93 | + |
| 94 | + if (!frontMatter.title) { |
| 95 | + FieldAction.done(); |
| 96 | + return; |
| 97 | + } |
| 98 | + |
| 99 | + const ollamaResp = await ollama.chat({ |
| 100 | + model: 'llama3', |
| 101 | + messages: [{ |
| 102 | + role: 'user', |
| 103 | + content: `Create a SEO friendly title based on the given placeholder title. The title should be catchy and should contain the main keywords. The title should not exceed 60 characters in length. Desired format: just a string, e.g. "My first blog post" and you should not include anything else than the title. |
| 104 | + |
| 105 | +The current placeholder title is: """${frontMatter.title}"""` |
| 106 | + }], |
| 107 | + stream: false |
| 108 | + }); |
| 109 | + |
| 110 | + let title = ollamaResp.message.content; |
| 111 | + |
| 112 | + if (!title) { |
| 113 | + FieldAction.done(); |
| 114 | + return; |
| 115 | + } |
| 116 | + |
| 117 | + if (title.startsWith('"') && title.endsWith('"')) { |
| 118 | + title = title.slice(1, -1); |
| 119 | + } |
| 120 | + |
| 121 | + FieldAction.update(title); |
| 122 | +})(); |
| 123 | +``` |
| 124 | + |
| 125 | +#### Prerequisites |
| 126 | + |
| 127 | +- Running [Ollama](https://ollama.com/) instance |
| 128 | +- `npm i ollama` |
| 129 | + |
| 130 | +#### Configuration |
| 131 | + |
| 132 | +```json {{ "title": "Update title" }} |
| 133 | +{ |
| 134 | + "frontMatter.taxonomy.contentTypes": [{ |
| 135 | + "name": "sample", |
| 136 | + "fields": [{ |
| 137 | + "title": "Title", |
| 138 | + "name": "title", |
| 139 | + "type": "string", |
| 140 | + "required": true, |
| 141 | + "actions": [{ |
| 142 | + "title": "Update title by Ollama AI", |
| 143 | + "script": "./scripts/fields/update-title.mjs", |
| 144 | + "command": "~/.nvm/versions/node/v20.11.1/bin/node" |
| 145 | + }] |
| 146 | + } |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +### Suggest titles by Ollama AI |
| 151 | + |
| 152 | +Similar to the previous script, this script will suggest multiple titles generated by the Ollama AI |
| 153 | +and you can choose one of them to update the title field value. |
| 154 | + |
| 155 | +> **Info**: The script makes use of the `askQuestions` method which allows you to ask the user to choose |
| 156 | +> from a list of options. |
| 157 | + |
| 158 | +```javascript {{ "title": "Suggest titles by Ollama AI" }} |
| 159 | +import { FieldAction } from '@frontmatter/extensibility'; |
| 160 | +import ollama from 'ollama'; |
| 161 | + |
| 162 | +(async () => { |
| 163 | + const { frontMatter, answers } = FieldAction.getArguments(); |
| 164 | + |
| 165 | + if (!answers) { |
| 166 | + if (!frontMatter.title) { |
| 167 | + FieldAction.done(); |
| 168 | + return; |
| 169 | + } |
| 170 | + |
| 171 | + const ollamaResp = await ollama.chat({ |
| 172 | + model: 'llama3', |
| 173 | + messages: [{ |
| 174 | + role: 'user', |
| 175 | + content: `Create a SEO friendly titles based on the given placeholder title. The titles should be catchy and should contain the main keywords. The titles should not exceed 60 characters in length. |
| 176 | + |
| 177 | +Desired format: just a string wrapped in quotes, e.g. "My first blog post" and you should not include anything else than the title. |
| 178 | + |
| 179 | +You should suggest at least 3 titles. Each suggestion is created on a new line. |
| 180 | + |
| 181 | +The current placeholder title is: """${frontMatter.title}"""` |
| 182 | + }], |
| 183 | + stream: false |
| 184 | + }); |
| 185 | + |
| 186 | + let titles = ollamaResp.message.content; |
| 187 | + |
| 188 | + if (!titles) { |
| 189 | + FieldAction.done(); |
| 190 | + return; |
| 191 | + } |
| 192 | + |
| 193 | + titles = titles.split('\n') |
| 194 | + .map(title => title.trim()) |
| 195 | + .filter(title => title && title.startsWith('"') && title.endsWith('"')) |
| 196 | + .map(title => { |
| 197 | + if (title.startsWith('"') && title.endsWith('"')) { |
| 198 | + title = title.slice(1, -1); |
| 199 | + } |
| 200 | + |
| 201 | + return title; |
| 202 | + }); |
| 203 | + |
| 204 | + FieldAction.askQuestions([{ |
| 205 | + name: "articleTitle", |
| 206 | + message: "Choose the best title", |
| 207 | + default: frontMatter.title, |
| 208 | + options: [decodeURIComponent(frontMatter.title), ...titles] |
| 209 | + }]); |
| 210 | + return; |
| 211 | + } |
| 212 | + |
| 213 | + if (!answers.articleTitle) { |
| 214 | + FieldAction.done(); |
| 215 | + return; |
| 216 | + } |
| 217 | + |
| 218 | + FieldAction.update(answers.articleTitle); |
| 219 | +})(); |
| 220 | +``` |
| 221 | + |
| 222 | +When the user triggers the field action, the script will ask the user to choose the best title |
| 223 | +from the suggestions it received from the Ollama AI. |
| 224 | + |
| 225 | +![Title suggestions by Ollama AI][03] |
| 226 | + |
| 227 | +#### Prerequisites |
| 228 | + |
| 229 | +- Running [Ollama](https://ollama.com/) instance |
| 230 | +- `npm i ollama` |
| 231 | + |
| 232 | +#### Configuration |
| 233 | + |
| 234 | +```json {{ "title": "Update title" }} |
| 235 | +{ |
| 236 | + "frontMatter.taxonomy.contentTypes": [{ |
| 237 | + "name": "sample", |
| 238 | + "fields": [{ |
| 239 | + "title": "Title", |
| 240 | + "name": "title", |
| 241 | + "type": "string", |
| 242 | + "required": true, |
| 243 | + "actions": [{ |
| 244 | + "title": "Suggest titles by Ollama AI", |
| 245 | + "script": "./scripts/fields/suggest-titles.mjs", |
| 246 | + "command": "~/.nvm/versions/node/v20.11.1/bin/node" |
| 247 | + }] |
| 248 | + } |
| 249 | +} |
| 250 | +``` |
| 251 | + |
| 252 | +<!-- Link References --> |
| 253 | + |
| 254 | +[01]: /docs/custom-actions#extensibility-library |
| 255 | +[02]: /releases/v10.3.0/field-actions.webp |
| 256 | +[03]: /releases/v10.3.0/field-actions-suggestions.webp |
0 commit comments