Skip to content

Commit

Permalink
docs: about usage of lingo-base
Browse files Browse the repository at this point in the history
  • Loading branch information
linonetwo committed May 6, 2024
1 parent 1301488 commit 855b103
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 13 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
created: 20240506172629040
modified: 20240506172629040
title: $:/config/PageControlButtons/Visibility/$:/core/ui/Buttons/language
type: text/vnd.tiddlywiki

show
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ title: language/en-GB/TraitTag developer - create TraitTag

As a developer, you will want to create your own TraitTag.

A TraitTag has a important field `"schema"`.
!! A TraitTag has a important field `"schema"`.

<$whiteboard tiddler="HowToCreateTraitTagDiagram" readonly="yes" height="750px" />

Expand All @@ -13,6 +13,8 @@ A TraitTag has a important field `"schema"`.

See links above to learn how to write them. You can also learn from some existed [[TraitTag Examples|$:/SuperTag/TraitTag]].

!! Online Tools

* Online free JSONSchema editors
** [ext[bjdash/JSON-Schema-Builder|https://bjdash.github.io/JSON-Schema-Builder/]]
** [ext[hellosean1025/json-schema-visual-editor|https://hellosean1025.github.io/json-schema-visual-editor/]]
Expand All @@ -23,7 +25,7 @@ See links above to learn how to write them. You can also learn from some existed
** [[wikilabs/field-editor - Side by side multiline field editor|https://tw-cpl.netlify.app/#Plugin_202203243721287]]


If you want to customise the form, follow these steps
!! If you want to customise the form, follow these steps

* Create a new tiddler, it is recommended to prefix it with `$:/TraitTag`, something like `$:/TraitTag/xxx`, followed by the custom English name, but it is fine not to do so.
* And add the tag `$:/SuperTag/TraitTag`, this is a must.
Expand Down Expand Up @@ -68,3 +70,25 @@ The value in properties is of the form `"completed": {"type": "boolean"},` with
The content inside can have title, description, type, format, etc.The type types are string, number, array, object, boolean, integer and integer. The number and integer types can have maximum and minimum value controls. At the same level as type in the properties field name is format, which can be `color` colour, `date` date value, `email` email format, etc. The combination of type and format allows for most form functionality. This can be learnt from the [[JSON Schema|https://json-schema.org/]] documentation or from the [[TraitTag Examples|$:/SuperTag/TraitTag]] examples. Normally JSON schema can nest data, but because of the Tiddlywiki there is no field levels that can be nested, so the format of nested data is not covered either.

The schema saves data in json format and the format is very strict, writing a wrong comma, missing a comma or writing a wrong semicolon or missing a semicolon will result in errors and will not display properly. You can edit it better with the help of the following URL or open it in a code editor such as VS Code, as there will be automatic checking and automatic formatting that will give a good indication of the problem.

!! Translation

Referring to [[$:/TraitTag/Color]], you can add the `lingo-base` field to the top level of the specification, e.g. `"lingo-base": "language/",`:

<$codeblock code={{$:/TraitTag/Color!!schema}} />

The usage is similar to that of the official Tiddlywiki `lingo` macro. This way, you can use translations in your trait tags.

In the example above, the actual translation tiddler used looks like this:

# `lingo-base` value
#* aka `language/`
# followed by the current language
#* For example, `en-GB/`.
# And then the contents of the field.
#* such as the field `"title": "TraitTag/Color/Title",` whose value
#* would be `TraitTag/Color/Title`.

And you end up with the translation tiddler [[language/en-GB/TraitTag/Color/Title]], Its content is

<$codeblock code={{language/en-GB/TraitTag/Color/Title}} />
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ title: language/zh-Hans/TraitTag developer - create TraitTag

作为一个开发者,你会想要创建你自己的特质标签。

一个特质标签有一个重要的字段`"schema"`。
!! 一个特质标签有一个重要的字段`"schema"`。

<$whiteboard tiddler="HowToCreateTraitTagDiagram" readonly="yes" height="750px" />

Expand All @@ -13,6 +13,8 @@ title: language/zh-Hans/TraitTag developer - create TraitTag

请看上面的链接来学习如何编写它们。你也可以从一些存在的[[特质标签例子|$:/SuperTag/TraitTag]]里学习用法。

!! 在线工具

* 在线免费的 JSON 规格编辑器
** [ext[bjdash/JSON-Schema-Builder|https://bjdash.github.io/JSON-Schema-Builder/]]
** [ext[hellosean1025/json-schema-visual-editor|https://hellosean1025.github.io/json-schema-visual-editor/]]
Expand All @@ -22,7 +24,7 @@ title: language/zh-Hans/TraitTag developer - create TraitTag
* 在创建特质标签条目时有用的太微插件
** [[wikilabs/field-editor - Side by side multiline field editor|https://tw-cpl.netlify.app/#Plugin_202203243721287]]

如果想要自定义表单的话,按照下面步骤
!! 如果想要自定义表单的话,参照下面的步骤

* 新建一个条目,建议以`$:/TraitTag`为前缀,类似`$:/TraitTag/xxx`,后面接上自定义的英文名,但不这样做也是可以的。
* 并加上标签`$:/SuperTag/TraitTag`,这是一定要的。
Expand Down Expand Up @@ -52,18 +54,40 @@ title: language/zh-Hans/TraitTag developer - create TraitTag

```
<$button>
<$action-createtiddler
tags={{{ [{$:/plugins/linonetwo/intention-tower-knowledge-graph/Config/task-tag}addsuffix[ ]addsuffix<currentTiddler>] }}}
tmo_taskState="New"
>
<$action-sendmessage $message="tm-edit-tiddler" $param=<<createTiddler-title>>/>
</$action-createtiddler>
{{$:/plugins/linonetwo/intention-tower-knowledge-graph/Images/Task}} 新任务
</$button>
<$action-createtiddler
tags={{{ [{$:/plugins/linonetwo/intention-tower-knowledge-graph/Config/task-tag}addsuffix[ ]addsuffix<currentTiddler>] }}}
tmo_taskState="New"
>
<$action-sendmessage $message="tm-edit-tiddler" $param=<<createTiddler-title>>/>
</$action-createtiddler>
{{$:/plugins/linonetwo/intention-tower-knowledge-graph/Images/Task}} 新任务
</$button>
```

properties里的值是`"completed": {"type": "boolean"},`的形式,字段名称用英文引号括起来,接着是一个英文冒号,然后是花括号,里面有写type属性,上面代码里是一个布尔值,显示在表单中的就会是true或false。常见的type值还有string字符串,number数字等。后面接一个英文的逗号,如果是最后一个就不用再写逗号了。如果选项是字符串类型,然后值是数组可供选择,那么可以采用enum,后面接一个中括号,值用英文引号括起来。

里面的内容可以有title、description、type、format等。type类型有string字符串、number数字、array数组、object对象、boolean布尔类型、integer整数类型。其中number和integer可以有最大值和最小值控制。在properties字段名称里与type同一层级的还有format,format可以是`color`颜色,也可以是`date`日期值,还可以是`email`邮件格式等。结合type和format可以实现大部分表单功能。具体可以通过[[JSON Schema|https://json-schema.org/]]文档来学习,或者从[[TraitTag Examples|$:/SuperTag/TraitTag]]示例中学习。一般的 JSON 规格是可以嵌套数据的,但因为在太微里,没有字段层级可以嵌套,所以也没有办法用表单输入嵌套数据。
里面的内容可以有 title、description、type、format 等。`type` 类型有:string字符串、number数字、array数组、object对象、boolean布尔类型、integer整数类型。其中 number 和 integer 可以有最大值和最小值控制。在properties字段名称里与type同一层级的还有format,format可以是`color`颜色,也可以是`date`日期值,还可以是`email`邮件格式等。结合type和format可以实现大部分表单功能。具体可以通过[[JSON Schema|https://json-schema.org/]]文档来学习,或者从[[TraitTag Examples|$:/SuperTag/TraitTag]]示例中学习。一般的 JSON 规格是可以嵌套数据的,但因为在太微里,没有字段层级可以嵌套,所以也没有办法用表单输入嵌套数据。

JSON 规格自身也是以 JSON 格式保存的数据,格式非常严格,写错了逗号,漏写了逗号,或者写错了分号,漏写了分号都会出错,不能正常显示。你可以借助下面的网址来更好地编辑或者在 VSCode 等代码编辑器里打开,因为会有自动检查和自动格式化,能够很好地提示问题。

!! 翻译内容

参考[[$:/TraitTag/Color]],你可以在规格的顶层加上 `lingo-base` 字段,例如 `"lingo-base": "language/",`:

<$codeblock code={{$:/TraitTag/Color!!schema}} />

其用法类似太微官方的 `lingo` 宏的用法。这样,你就可以在你的特质标签中使用翻译了。

在上面的例子里,实际使用的翻译条目是这样的:

# `lingo-base` 的值
#* 也就是 `language/`
# 后面拼上当前语言
#* 例如 `zh-Hans/`
# 然后拼上字段的内容
#* 例如 `"title": "TraitTag/Color/Title",` 这个字段
#* 拼上的就会是 `TraitTag/Color/Title`

最终得到 [[language/zh-Hans/TraitTag/Color/Title]] 这个翻译条目,其内容为

<$codeblock code={{language/zh-Hans/TraitTag/Color/Title}} />

0 comments on commit 855b103

Please sign in to comment.