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.

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()

Count number of tags

Counts a number of tags in the database.

Parameters

No parameters.

Returns

Returns a number of tags stored in the database.

Request

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

Response

5

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"
}
Can you help us improve the docs? 🙏

The source of these docs is here on GitHub. If you see a way these docs can be improved, please fork us!