Documentation

Developer reference for WP Notepad: storage format, hooks, REST API and options.

Storage location and keys

Notes are stored in the visitor’s browser localStorage. The key depends on how the notepad is placed:

PlacementStorage key
Classic widget{widget_id}-textarea
Shortcodevalue of the id attribute (auto-generated if omitted)
Blockwpnotepad-block-{notepadKey}
Tabs (second and later){baseKey}-tab-{N}

On multisite sub-sites the keys above get a per-site prefix, site{ID}-- (changeable with the wpnotepad_key_prefix filter). The main site and single sites use no prefix.

Storage format

Since 2.0.0 notes are stored as a small timestamped JSON envelope. Plain strings saved by older versions are read transparently.

{ "v": 2, "time": 1750000000000, "value": "note text", "u": "…" }
  • time is epoch milliseconds, used for note expiry (TTL) and for conflict resolution in cross-device sync (last-write-wins).
  • When the textarea has a data-ttl value (days), notes whose now - time exceeds it are removed on load.
  • u is an owner tag (an opaque per-user value) added only to notes written while logged in on a site that uses sync. On such sites, notes of other owners are neither shown nor synced.
  • A cleared note is kept as an empty, timestamped value so an older copy on another device cannot bring it back.

Filters

FilterDescription
wpnotepad_widget_textareaReceives the widget’s whole notepad markup (tab bar, textarea, toolbar, status) for customization
wpnotepad_widget_descriptionFilters the widget’s description output
wpnotepad_key_prefixStorage key prefix (default: site{ID}-- on sub-sites, empty otherwise). Only letters, digits, _ and - are kept
wpnotepad_import_max_bytesLargest file size (bytes) the “Import” button reads. Argument int $bytes (default 2097152 = 2 MB); return an integer. Larger files are refused before they are read. 0 removes the limit (since 2.9.0)
wpnotepad_user_can_syncWhether a logged-in user may use cross-device sync. Arguments bool $can (default true) and int $user_id; return a boolean. Only called while sync is enabled and the user is logged in. Users for whom it returns false stay browser-only like guests, and the REST API answers 403 for them. By default every logged-in user is included (on multisite, also network users who are not members of the site). Notes synced before a user was excluded stay on the server (they can be removed with the personal data eraser or “Delete all synced notes”) (since 2.9.0)
/**
 * Example: wrap the widget's notepad markup.
 *
 * @param string $markup The whole notepad markup.
 */
add_filter( 'wpnotepad_widget_textarea', function ( $markup ) {
	return '<div class="my-notepad-wrap">' . $markup . '</div>';
} );
/**
 * Example: limit sync to editors and above, and lower the import limit to 1 MB.
 *
 * @param bool $can     Whether the user may sync (default true).
 * @param int  $user_id User ID.
 */
add_filter( 'wpnotepad_user_can_sync', function ( $can, $user_id ) {
	return $can && user_can( $user_id, 'edit_others_posts' );
}, 10, 2 );

add_filter( 'wpnotepad_import_max_bytes', function () {
	return 1048576;
} );

REST API (cross-device sync)

Opt-in cross-device sync uses a REST API under the wp-notepad/v1 namespace. Routes are available only when sync is enabled and the user is logged in (cookie auth plus the X-WP-Nonce header); otherwise they return 401 / 403. Users excluded by wpnotepad_user_can_sync also get 403.

EndpointMethodDescription
/wp-json/wp-notepad/v1/notesGETGet all notes of the logged-in user. The X-WPNotepad-Erased-At header gives the time of the last erasure or purge
/wp-json/wp-notepad/v1/notesPOSTSave a note (key / value required, time optional). An empty value is stored as a cleared note (tombstone)
/wp-json/wp-notepad/v1/notes/{key}DELETEDelete the note with the given key
  • Keys must match [A-Za-z0-9_-]{1,191} (400 otherwise). Values are cut at 100,000 characters.
  • Writes with a time older than the stored copy are ignored (saved: false); a future time is clamped to the server’s current time. Writes stamped before an erasure or purge are not accepted.
  • Per user: 200 notes (409), 1 MB in total (413), 500 rows including cleared notes (a new key over that evicts the oldest cleared notes first).
  • On the server each note is one user meta row, rwc_wpnotepad_note:{key}. The old format (an array in rwc_wpnotepad_notes) is migrated on first access.
  • The front end reads window.wpNotepad (syncSite, keyPrefix, importMaxBytes, i18n, plus restUrl / nonce / user for users who may sync).

Block

The block (rwc/wpnotepad) is a dynamic block rendered on the server (since 2.2.0). Its attributes are stored in the block comment and its markup comes from the same template as the widget and shortcode. Static blocks saved by earlier versions keep showing their saved HTML until re-saved, and are migrated automatically when opened in the editor.

Options and metadata

NameTypeDescription
rwc_wpnotepad_sync_enabledOptionEnables/disables cross-device sync (default: disabled). Toggled under Settings → WP Notepad
rwc_wpnotepad_note:{key}User metaA synced note (value / time)
rwc_wpnotepad_erased_atUser metaWhen the user’s data was erased (earlier writes are refused)
rwc_wpnotepad_purged_atNetwork optionWhen “Delete all synced notes” was used
rwc_wpnotepad_prefix_sinceNetwork optionWhen multisite storage-key prefixes took effect (used to decide which old notes a sub-site may carry over)

Privacy

  • Synced notes are included in WordPress’s personal data export and erasure (Tools menu). Cleared notes are not exported.
  • Suggested privacy policy text is added to the guide under Settings → Privacy.
  • Nothing is sent to the server while sync is disabled, or for guests.

Uninstall

Deleting the plugin removes the sync setting (on every site), all users’ synced notes and the erase/purge records. Visitors’ notes live in their browsers (LocalStorage), so they are not removed from the site side. rwc_wpnotepad_prefix_since (a single timestamp with no personal data) is deliberately kept so that a reinstall cannot make sub-sites pick up main-site notes.

Source code

Copied title and URL