| Platform | Architecture | Application | Build command |
|---|---|---|---|
| macOS | x86_64 | Desktop / Electron app | ./bin/build-mac-x64.sh |
| ARM 64 | Desktop / Electron app | ./bin/build-mac-arm64.sh | |
| Linux | x86_64 | Desktop / Electron app | ./bin/build-linux-x64.sh |
| Server | ./bin/build-server.sh | ||
| Windows | x86_64 | Desktop / Electron app | ./bin/build-win-x64.sh |
| Desktop client | Server |
|---|---|
| |
Hello
"); + this.$widget.show(); + } + + async entitiesReloadedEvent({loadResults}) { + if (loadResults.isNoteReloaded(this.noteId)) { + this.refresh(); + } + } +} \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Loading data.md b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Loading data.md new file mode 100644 index 000000000..a29207b15 --- /dev/null +++ b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Loading data.md @@ -0,0 +1,9 @@ +# Loading data +Data loading can be done in `doRefresh()` since it gets a reference to the note: + +```plain +const blob = await note.getBlob(); +const content = blob.getJsonContent(); +``` + +Note that `doRefresh` can sometimes be called by Saving data via spaced update when the user makes a changes, this has to be accounted for. \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Note type checklist.md b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Note type checklist.md new file mode 100644 index 000000000..9b81ae39c --- /dev/null +++ b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Note type checklist.md @@ -0,0 +1,49 @@ +# Note type checklist +The goal of this checklist is to ensure a good implementation or re-test of a note type. + +## Implementation checklist + +The note type widget must be created according to First steps: + +* Register the note type in the server +* Register the note type in the client context menu +* Create a type widget +* Register the type widget +* Add the default icon mapping +* Add to note type selector +* Add the note to server allowed note types +* Update demo document to include this new note type +* Increase server sync version (see Mindmap gets turned as file). + +## Validation checklist + +### Ensure that the note renders properly + +* When refreshing to a note that is already displayed +* When going to another note and then going back +* When creating a new note of the given type +* Have two tabs of the same note type and switch between them + +### Ensure data persistence + +* Save data when modifying changes via spaced update + +### Ensure data retrieval + +* Go on a note of this type and refresh the page +* Create a new note of this type while on another note of this type and ensure that the content is set properly. + +### Set up a note preview + +For an implementation reference, see SVG rendering. + +* Note preview rendering (go to parent and see note list). +* Include note +* Share +* Note revisions + +### Import/export + +* Export & Import, making sure no data is lost in the process. +* Remove the data folder entirely to test that the demo document is well imported on first setup. + * Ensure that the preview also works (check the preview in the root note). \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/SVG rendering.md b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/SVG rendering.md new file mode 100644 index 000000000..3deb8f2d1 --- /dev/null +++ b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/SVG rendering.md @@ -0,0 +1,72 @@ +# SVG rendering +For diagrams and similar note types, it makes sense to cache an SVG rendering of the content so that it can be used for: + +* Content preview in note lists (when viewing the list of notes from the parent note). +* Note inclusion +* Share + +## Step 1. Save the SVG content as an attachment + +The first step is to obtain the SVG from the custom widget used. For example, for Mind Elixir there is an `exportSvg` method. + +If the returned value is a `Blob`, then the underlying text can be obtained via `await blob.text()`. + +To save the SVG as an attachment alongside the content, simply modify `getData()`: + +```plain +async getData() { + const mind = this.mind; + if (!mind) { + return; + } + + const svgContent = await this.mind.exportSvg().text(); + return { + content: mind.getDataString(), + attachments: [ + { + role: "image", + title: "mindmap-export.svg", + mime: "image/svg+xml", + content: svgContent, + position: 0 + } + ] + }; +} +``` + +You can test this step by making a change to the note and then using the “Note attachments” option from the note menu. + +## Step 2. Adapting the server to serve SVG attachment + +The `src/routes/api/image.ts` route is in charge for serving the image previews of image notes, but also of custom note types such as canvases. + +Alter the `returnImageInt` method as follows: + +1. Add the image type to the guard condition which returns 400 for unsupported note types. +2. Add an `if` statement to render the attachment using the correct name: + +```plain +if (image.type === "mindMap") { + renderSvgAttachment(image, res, 'mindmap-export.svg'); +} +``` + +## Step 3. Serve the SVG attachment for note preview + +The client also needs tweaking to allow it to render SVG attachments by calling the previously modified server route. + +The `src/public/app/services/content_renderer.js` file is in charge of handling the previews. To render using the image route, modify `getRenderedContent` to add the new note type to the `if` which calls `renderImage`. + +## Step 4. Serve SVG for share + +By default, `Note type cannot be displayed` will be displayed when trying to access the given note via a share. + +To serve the SVG, open `src/share/content_renderer.ts` and look for `getContent`. Then add to the `if` containing `renderImage` the new note type. + +This is not enough, as attempting to access the shared note will result in a broken image that fails with `Requested note is not a shareable image`. To solve this one, go to `src/share/routes.ts` and add a `renderImageAttachment` statement to `router.get('/share/api/images/[…])`. + +## Step 5. Serve SVG for revisions + +In the revisions list, to display the SVG, go to `src/public/app/widgets/dialogs/revisions.js` and look for the `renderContent` method. Simply add the note type to one of the already existing `if`s, such as the one for `canvas` and `mindMap` or `mermaid` (if the text content of the diagram should also be displayed). \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Saving data via spaced update.md b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Saving data via spaced update.md new file mode 100644 index 000000000..b6344cb78 --- /dev/null +++ b/docs/Developer Guide/Developer Guide/Development and architecture/Adding a new note type/Saving data via spaced update.md @@ -0,0 +1,27 @@ +# Saving data via spaced update +The data persistence is achieved via the spaced update mechanism which is already present and needs to be integrated within the newly created type widgets. + +First, the class must implement `getData`, in order to retrieve the data from the custom widget in a serialized form. As an example from the mind map implementation: + +```plain +async getData() { + const mind = this.mind; + if (!mind) { + return; + } + + return { + content: mind.getDataString() + }; +} +``` + +Here the content is a string containing a JSON. It is also possible to provide attachments here as well, such as SVG rendering to provide a preview of the content. + +Then to trigger an update, register a listener within the custom widget that calls the spaced update, for example: + +```plain +mind.bus.addListener("operation", (operation) => { + this.spacedUpdate.scheduleUpdate(); +}); +``` \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Backlinks.md b/docs/Developer Guide/Developer Guide/Development and architecture/Backlinks.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Branch prefixes.md b/docs/Developer Guide/Developer Guide/Development and architecture/Branch prefixes.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Build information.md b/docs/Developer Guide/Developer Guide/Development and architecture/Build information.md new file mode 100644 index 000000000..509386e08 --- /dev/null +++ b/docs/Developer Guide/Developer Guide/Development and architecture/Build information.md @@ -0,0 +1,4 @@ +# Build information +* Provides context about when the build was made and the corresponding Git revision. +* The information is displayed to the client when going in the about dialog. +* The build information is hard-coded in `src/services/build.ts`. This file is generated automatically via `npm run update-build-info` which itself is run automatically whenever making a build in the CI, or a [local delivery](../Building%20and%20deployment/Build%20deliveries%20locally.md). \ No newline at end of file diff --git a/docs/Developer Guide/Developer Guide/Development and architecture/Database/attachments.md b/docs/Developer Guide/Developer Guide/Development and architecture/Database/attachments.md new file mode 100644 index 000000000..cbe7e6735 --- /dev/null +++ b/docs/Developer Guide/Developer Guide/Development and architecture/Database/attachments.md @@ -0,0 +1,2 @@ +# attachments +| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
attachmentId | Text | Non-null | Unique ID (e.g. qhC1vzU4nwSE) | |
ownerId | Text | Non-null | The unique ID of a row in notes. | |
role | Text | Non-null | The role of the attachment: image for images that are attached to a note. | |
mime | Text | Non-null | The MIME type of the attachment (e.g. image/png) | |
title | Text | Non-null | The title of the attachment. | |
isProtected | Integer | Non-null | 0 | 1 if the entity is protected, 0 otherwise. |
position | Integer | Non-null | 0 | Not sure where the position is relevant for attachments (saw it with values of 10 and 0). |
blobId | Text | Nullable | null | The corresponding blobId from the blobs table. |
dateModified | Text | Non-null | Localized modification date (e.g. 2023-11-08 18:43:44.204+0200) | |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
utcDateScheduledForErasure | Text | Nullable | null | |
isDeleted | Integer | Non-null | 1 if the entity is deleted, 0 otherwise. | |
deleteId | Text | Nullable | null |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
attributeId | Text | Non-null | Unique Id of the attribute (e.g. qhC1vzU4nwSE), can also have a special unique ID for Special notes (e.g. _lbToday_liconClass). | |
noteId | Text | Non-null | The ID of the note this atttribute belongs to | |
type | Text | Non-null | The type of attribute (label or relation). | |
name | Text | Non-null | The name/key of the attribute. | |
value | Text | Non-null | "" |
|
position | Integer | Non-null | 0 | The position of the attribute compared to the other attributes. Some predefined attributes such as originalFileName have a value of 1000. |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
isDeleted | Integer | Non-null | 1 if the entity is deleted, 0 otherwise. | |
deleteId | Text | Nullable | null | |
isInheritable | Integer | Nullable | 0 |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
blobId | Text | Non-null | The unique ID of the blob (e.g. XXbfAJXqWrYnSXcelLFA). | |
content | Text | Nullable | null | The content of the blob, can be either:
|
dateModified | Text | Non-null | Localized modification date (e.g. 2023-11-08 18:43:44.204+0200) | |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
branchId | Text | Non-null | The ID of the branch, in the form of a_b where a is the parentNoteId and b is the noteId. | |
noteId | Text | Non-null | The ID of the note. | |
parentNoteId | Text | Non-null | The ID of the parent note the note belongs to. | |
notePosition | Integer | Non-null | The position of the branch within the same level of hierarchy, the value is usually a multiple of 10. | |
prefix | Text | Nullable | The branch prefix if any, or NULL otherwise. | |
isExpanded | Integer | Non-null | 0 | Whether the branch should appear expanded (its children shown) to the user. |
isDeleted | Integer | Non-null | 0 | 1 if the entity is deleted, 0 otherwise. |
deleteId | Text | Nullable | null | |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
id | Integer | Nullable | A sequential numeric index of the entity change. | |
entityName | Text | Nullable | The type of entity being changed (attributes, branches, note_reordering, etc.) | |
entityId | Text | Nullable | The ID of the entity being changed. | |
hash | Text | Nullable | TODO: Describe how the hash is calculated | |
isErased | Integer | Nullable | TODO: What does this do? | |
changeId | Text | Nullable | TODO: What does this do? | |
componentId | Text | Nullable | TODO: What does this do? | |
instanceId | Text | Nullable | TODO: What does this do? | |
isSynced | Integer | Nullable | TODO: What does this do? | |
utcDateChanged | Text | Nullable | Date of the entity change in UTC format (e.g. 2023-11-08 16:43:44.204Z) |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
etapiTokenId | Text | Non-null | A unique ID of the token (e.g. aHmLr5BywvfJ). | |
name | Text | Non-null | The name of the token, as is set by the user. | |
tokenHash | Text | Non-null | The token itself. | |
utcDateCreated | Text | Non-null | Creation date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
isDeleted | Integer | Non-null | 0 | 1 if the entity is deleted, 0 otherwise. |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
noteId | Text | Non-null | The unique ID of the note (e.g. 2LJrKqIhr0Pe). | |
title | Text | Non-null | "note" | The title of the note, as defined by the user. |
isProtected | Integer | Non-null | 0 | 1 if the entity is protected, 0 otherwise. |
type | Text | Non-null | "text" | The type of note (i.e. text, file, code, relationMap, mermaid, canvas). |
mime | Text | Non-null | "text/html" | The MIME type of the note (e.g. text/html).. Note that it can be an empty string in some circumstances, but not null. |
isDeleted | Integer | Nullable | 0 | 1 if the entity is deleted, 0 otherwise. |
deleteId | Text | Non-null | null | |
dateCreated | Text | Non-null | Localized creation date (e.g. 2023-11-08 18:43:44.204+0200) | |
dateModified | Text | Non-null | Localized modification date (e.g. 2023-11-08 18:43:44.204+0200) | |
utcDateCreated | Text | Non-null | Creation date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
blobId | Text | Nullable | null | The corresponding ID from blobs. Although it can theoretically be NULL, haven't found any such note yet. |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
name | Text | Non-null | The name of option (e.g. maxContentWidth) | |
value | Text | Non-null | The value of the option. | |
isSynced | Integer | Non-null | 0 | 0 if the option is not synchronized and thus can differ between clients, 1 if the option is synchronized. |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
noteId | Text | Non-null | Unique ID of the note (e.g. yRRTLlqTbGoZ). | |
notePath | Text | Non-null | The path (IDs) to the note from root to the note itself, separated by slashes. | |
utcDateCreated | Text | Non-null | Creation date in UTC format (e.g. 2023-11-08 16:43:44.204Z) |
| Column Name | Data Type | Nullity | Default value | Description |
|---|---|---|---|---|
revisionId | TextText | Non-null | Unique ID of the revision (e.g. 0GjgUqnEudI8). | |
noteId | Text | Non-null | ID of the note this revision belongs to. | |
type | Text | Non-null | "" | The type of note (i.e. text, file, code, relationMap, mermaid, canvas). |
mime | Text | Non-null | "" | The MIME type of the note (e.g. text/html). |
title | Text | Non-null | The title of the note, as defined by the user. | |
isProtected | Integer | Non-null | 0 | 1 if the entity is protected, 0 otherwise. |
blobId | Text | Nullable | null | The corresponding ID from blobs. Although it can theoretically be NULL, haven't found any such note yet. |
utcDateLastEdited | Text | Non-null | Not sure how it differs from modification date. | |
utcDateCreated | Text | Non-null | Creation date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
utcDateModified | Text | Non-null | Modification date in UTC format (e.g. 2023-11-08 16:43:44.204Z) | |
dateLastEdited | Text | Non-null | Not sure how it differs from modification date. | |
dateCreated | Text | Non-null | Localized creatino date (e.g. 2023-08-12 15:10:04.045+0300) |
| Name | Resolution | Description |
|---|---|---|
icon-black.svg | 53x40 | Used by the global menu button when not hovered. |
icon-color.svg | 53x40 | Used by the global menu when hovered. |
icon-grey.svg | 53x40 | Used by the dark theme, in place of icon-black.svg. |
| Name | Resolution | Description |
|---|---|---|
ios/apple-touch-icon.png | 180x180 | Used as apple-touch-icon, but only in login.ejs and set_password.ejs for some reason. |
mac/icon.icns | 512x512 | Provided as --icon to electron-packager for mac-arm64 and mac-x64 builds. |
png/128x128.png | 128x128 | Used in linux-x64 build, to provide an icon.png. |
png/256x256-dev.png | 256x256 | Used by the Electron window icon, if in dev mode. |
png/256x256.png | Used by the Electron window icon, if not in dev mode. | |
win/icon.ico |
|
|
win/setup-banner.gif | 640x480 | Used by the Squirrel Windows installer during the installation process. Has only one frame. |
| Before |  |
|---|---|
| After |  |
| With new scale |  |
| 0.9 |  |
|---|---|
| 0.85 |  |
| 0.8 |  |
| 0.75 |  |
The electron.icns from the resulting build | The icon source |
|---|---|
| |
| Name | Resolution | Description |
|---|---|---|
icon-black.png | 36x36 | Does not appear to be used. |
icon-color.png | 36x36 | Used only by some tests in test-etapi. |
icon-grey.png | 36x36 | Does not appear to be used. |
icon.svg | 210x297 | Does not appear to be used. |
| Name | Resolution | Description |
|---|---|---|
png/16x16-bw.png | 16x16 | Do not appear to be used. |
png/16x16.png | ||
png/24x24.png | 24x24 | |
png/32x32.png | 32x32 | |
png/48x48.png | 48x48 | |
png/64x64.png | 64x64 | |
png/96x96.png | 96x96 | |
png/512x512.png | 512x512 | Does not appear to be used. |
win/setup-banner.xcf | GIMP source for win/setup-banner.gif. Provided only for future editing. |
| Note Type | type value | Corresponding MIME type | Content of the note's blob | Relevant attributes |
|---|---|---|---|---|
| Text | text | The HTML of the note. | ||
| Relation Map | relationMap | application/json | A JSON describing the note: | None |
| Render Note | render | text/html or blank. | An empty blob. | ~renderNote pointing to the HTML note to render. |
| Canvas | canvas | application/json | | None |
| Mermaid Diagram | mermaid | text/mermaid or text/plain | The plain text content of the Mermaid diagram. | None |
| Book | book | text/html or blank. | An empty blob. |
both options are shown to the user via the “Book Properties” ribbon widget. |
| Web View | webView | blank | An empty blob. | #webViewSrc pointing to an URL to render. |
| Code | code | Depends on the language (e.g. text/plain, text/x-markdown, text/x-c++src). | The plain text content. |
| Dependency | Name in library_loader | Things to check for a basic sanity check | Protected by unit tests | |
|---|---|---|---|---|
better-sqlite3 | See bettersqlite binaries. | |||
jsdom |
| Protected by typings, should catch any potential changes in API. | Yes | |
async-mutex |
| |||
axios |
| |||
sax |
| |||
|
| |||
ejs |
| |||
dayjs |
| |||
semver |
| |||
https-proxy-agent | ??? | |||
sax |
| |||
ini |
| |||
jsplumb | RELATION_MAP |
| ||
jquery.mark.es6 | MARKJS |
| ||
knockout.js |
| |||
normalize.min.css |
| |||
wheel-zoom.min.js | WHEEL_ZOOM |
| ||
fancytree |
| |||
bootstrap |
| |||
electron-debug |
| |||
electron-dl | ||||
eslint | ||||
marked |
| Yes | ||
force-graph |
|
better-sqlite3 version | SQLite version | Node.js prebuilds | Electron.js prebuilds |
| 8.4.0 | <3.43.0 | v20 | ??? |
| 8.5.0 | v20 | v25 | |
| 8.5.1 | v26 | ||
| 8.5.2 | v20 (macOS + arm64) | ||
| 8.6.0 | 3.43.0 | ||
| 8.7.0 | 3.43.1 | ||
| 9.0.0 | 3.43.2 | v27 | |
| 9.1.0 | 3.44.0 | ||
| 9.1.1 | macOS + Alpine | ||
| 9.2.0 | 3.44.2 | ||
| 9.2.1 / 9.2.2 | v28 | ||
| 9.3.0 | 3.45.0 | ||
| 9.4.0 | 3.45.1 | ||
| 9.4.1 | Windows arm, arm64 | ||
| 9.4.2 | <v29 | ||
| 9.4.3 | <v29 | ||
| 9.4.4 | v29 | ||
| 9.4.5 | Better prebuilds | ||
| 9.5.0 | 3.45.2 | ||
| 9.6.0 | 3.45.3 | v30 | |
| 10.0.0 | v22 | ||
| 10.1.0 | 3.46.0 | ||
| 11.0.0 | >21 | ||
| 11.1.0 (prerelease) | v31 | ||
| 11.1.1 | |||
| 11.1.2 |
better-sqlite3 versionChange log | SQLite version Change log | Compatibility with upstream Trilium |
|---|---|---|
| 8.4.0 | <3.43.0 | Compatible, same version. |
| 8.6.0 | 3.43.0 | |
| 8.7.0 | 3.43.1 | |
| 9.0.0 | 3.43.2 | |
| 9.1.0 + 9.1.1 | 3.44.0 | |
| 9.2.0 + 9.2.1 + 9.2.2 | 3.44.2 | |
| 9.3.0 | 3.45.0 | |
| 9.4.0, 9.4.1, 9.4.2, 9.4.3, 9.4.4, 9.4.5 | 3.45.1 | |
| 9.5.0 | 3.45.2 | |
| 9.6.0 / 10.0.0 | 3.45.3 | |
| 10.1.0 / 11.0.0 / 11.1.1 / 11.1.2 / 11.2.0 / 11.2.1 | 3.46.0 | |
| 11.3.0 | 3.46.1 |
| Affected file | Affected method | Changed in | Reason for change |
|---|---|---|---|
packages/ckeditor5-mention/src/mentionui.ts | createRegExp() | 6db05043be24bacf9bd51ea46408232b01a1b232 (added back) | Allows triggering the autocomplete for labels and attributes in the attribute editor. |
init() | 55a63a1934efb9a520fcc2d69f3ce55ac22aca39 | Allows dismissing @-mention permanently after pressing ESC, otherwise it would automatically show up as soon as a space was entered. |
| trilium-ckeditor5 | 43.2.0 | |
ckeditor5-math | See ckeditor5-math. | |
ckeditor5-math in action.To run the server-side tests: To view the code coverage for the server: Afterwards, a friendly HTML report can be found in | To run the client-side tests: To view the code coverage for the client: Afterwards, a friendly HTML report can be found in |
