Tags

Tags let you add keywords to notes, making them easier to find and browse when you've got a lot of them. Use tags when a note might apply to more than one category or when you want to filter results in a certain notebook by a keyword.

The tag model

The tag model contains all the information about your tags, such as their name, associated color, creation and modification timestamps, and any other metadata.

Properties

Name
_id
Type
string
Description
The unique tag ID which should start with tag: and the remains are randomly generated string. Pattern: ^tag: Length: 6..128
Name
_rev
Type
string
Description
This is a CouchDB specific field. The current MVCC-token/revision of this document (mandatory and immutable).
Name
color
Type
string
Description
The color type of the tag. One of: "default", "red", "orange", "yellow", "olive", "green", "teal", "blue", "violet", "purple", "pink", "brown", "grey", "black"
Name
count
Type
number
Description
It indicates the number of notes with the tag.
Name
createdAt
Type
number
Description
The date time when the tag was created, represented with Unix timestamps in milliseconds.
Name
name
Type
string
Description
The name of the tag. Length: 0..64
Name
updatedAt
Type
number
Description
The date time when the tag was last updated, represented with Unix timestamps in milliseconds.

The tag object

{
  "_id": "tag:tBELDUITs",
  "_rev": "5-caf95ffd831665119f6d4f01113cdab4",
  "count": 3,
  "color": "green",
  "createdAt": 1482130519215,
  "updatedAt": 1493014639273,
  "name": "Admin"
}

The tag class

The Tag class is a wrapper class of the tag, providing various methods for its operations such as loading, validation, saving, and serialization.

Methods

Name
static loadWithId(tagId: string)
Type
Description
Loads a tag by its ID from the local database and returns a new instance of the Tag.
Name
constructor(initialValues: Partial<Tag>)
Type
Description
Initializes a new Tag instance with the given initial values. If no values are provided, it assigns default values.
Name
validate()
Type
Description
Validates the current tag instance based on the predefined validation rules. If valid, returns an empty array. If not, returns the list of validation errors.
Name
save()
Type
Description
Validates and then saves the tag to the local database. Throws an error if the validation fails or if there's a problem with the saving process.
Name
toObject()
Type
Description
Converts the tag instance into a plain JavaScript object.
Name
toJson()
Type
Description
Serializes the tag instance into a JSON string.

Import the class

const { Tag } = require('inkdrop').models

Load a tag from the database

const tag = await Tag.loadWithId('tag:9dc6a7a7')

Create a new tag

const tag = new Tag({
  name: 'My tag'
})

Change its name

tag.name = 'Updated tag'

Save the changes

await tag.save()

Convert the tag into a plain object

const object = tag.toObject()

Convert the tag into JSON

const json = tag.toJson()

get(docId, options)

Retrieve a tag

Retrieve a tag with the given ID.

Parameters

Name
docId
Type
string
Required
Description
The tag ID
Name
options
Type
object
Description
Options. See PouchDB's documentation for available options.

Returns

Returns a tag if a valid tag ID was provided.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const tag = await db.tags.get('tag:tBELDUITs')

Response

{
  "_id": "tag:tBELDUITs",
  "_rev": "5-caf95ffd831665119f6d4f01113cdab4",
  "count": 3,
  "color": "green",
  "createdAt": 1482130519215,
  "updatedAt": 1493014639273,
  "name": "Admin"
}

all()

List all tags

Retrieve a list of your tags.

Parameters

No parameters

Returns

Returns a list of tags.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const list = await db.tags.all()

Response

[
  {
    "_id": "tag:tBELDUITs",
    "_rev": "5-caf95ffd831665119f6d4f01113cdab4",
    "count": 3,
    "color": "green",
    "createdAt": 1482130519215,
    "updatedAt": 1493014639273,
    "name": "Admin"
  },
  ...
]

createId(): string

Create a tag ID

Creates new tag ID which is String

Parameters

No parameters

Returns

Returns a new tag ID.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const tagId = await db.tags.createId()

Response

"tag:ak0s1ce6"

validateDocId(): boolean

Validate a tag ID

Tests if the given docId is a valid tag ID

Parameters

Name
docId
Type
string
Required
Description
A document ID to validate

Returns

Returns true if valid

Request

const db = inkdrop.main.dataStore.getLocalDB()
const isValid = await db.tags.validateDocId('tag:ak0s1ce6')

Response

true

put(doc)

Create or update a tag

Create a new tag or update an existing note. If the tag already exists, you must specify its revision _rev, otherwise a conflict will occur.

Parameters

Name
doc
Type
object
Required
Description
A Tag data to store

Returns

It throws an InvalidDataError if the given doc was invalid. The response contains the id of the document, the new rev, and an ok to reassure you that everything is okay.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const result = await db.tags.put({
  _id: 'tag:9IoGtoCuv',
  updatedAt: 1475549348850,
  createdAt: 1475549348850,
  name: 'New tag',
  color: 'green',
  count: 0
})

Response

{
  "ok": true,
  "id": "tag:9IoGtoCuv",
  "rev": "1-a6157a5ea545c99b00ff904eef05fd9f"
}

remove(docId)

Remove a tag

Deletes a tag with the given tag ID.

This method does not de-associate the tag from notes. Use db.utils.deleteTag(tagId)

Parameters

Name
docId
Type
string
Required
Description
A tag ID to delete.

Returns

The response contains the id of the document, the new rev, and an ok to reassure you that everything is okay.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const result = await db.tags.remove("tag:9IoGtoCuv")

Response

{
  "ok": true,
  "id": "tag:9IoGtoCuv",
  "rev": "2-9af304be281790604d1d8a4b0f4c9adb"
}

countAll()

Request

const db = inkdrop.main.dataStore.getLocalDB()
const num = await db.tags.countAll()

Response

findWithName(name)

Lookup a tag by name

Retrieves a tag with the given name.

Parameters

Name
name
Type
string
Required
Description
A tag name to find.

Returns

Returns a tag if found otherwise undefined.

Request

const db = inkdrop.main.dataStore.getLocalDB()
const tag = await db.tags.findWithName('Videography')

Response

{
  "name": "Videography",
  "color": "red",
  "updatedAt": 1662946230118,
  "createdAt": 1662946219086,
  "count": 0,
  "_id": "tag:ZiQET3lID",
  "_rev": "2-23c30db926215b718dae860556277fd5"
}