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:
| Placement | Storage key |
|---|---|
| Classic widget | {widget_id}-textarea |
| Shortcode | value of the id attribute (auto-generated if omitted) |
| Block | wpnotepad-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": "…" }
timeis epoch milliseconds, used for note expiry (TTL) and for conflict resolution in cross-device sync (last-write-wins).- When the textarea has a
data-ttlvalue (days), notes whosenow - timeexceeds it are removed on load. uis 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
| Filter | Description |
|---|---|
wpnotepad_widget_textarea | Receives the widget’s whole notepad markup (tab bar, textarea, toolbar, status) for customization |
wpnotepad_widget_description | Filters the widget’s description output |
wpnotepad_key_prefix | Storage key prefix (default: site{ID}-- on sub-sites, empty otherwise). Only letters, digits, _ and - are kept |
wpnotepad_import_max_bytes | Largest 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_sync | Whether 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.
| Endpoint | Method | Description |
|---|---|---|
/wp-json/wp-notepad/v1/notes | GET | Get 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/notes | POST | Save a note (key / value required, time optional). An empty value is stored as a cleared note (tombstone) |
/wp-json/wp-notepad/v1/notes/{key} | DELETE | Delete 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
timeolder than the stored copy are ignored (saved: false); a futuretimeis 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 inrwc_wpnotepad_notes) is migrated on first access. - The front end reads
window.wpNotepad(syncSite,keyPrefix,importMaxBytes,i18n, plusrestUrl/nonce/userfor 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
| Name | Type | Description |
|---|---|---|
rwc_wpnotepad_sync_enabled | Option | Enables/disables cross-device sync (default: disabled). Toggled under Settings → WP Notepad |
rwc_wpnotepad_note:{key} | User meta | A synced note (value / time) |
rwc_wpnotepad_erased_at | User meta | When the user’s data was erased (earlier writes are refused) |
rwc_wpnotepad_purged_at | Network option | When “Delete all synced notes” was used |
rwc_wpnotepad_prefix_since | Network option | When 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.