Operator guideENurlsformcms

URLs / Form

Embedded page-level URL editor opened from CMS Page Editor to add, update, save, and remove URL rows for one page key.

Reader view

Clean portal guidance

This page keeps the operator explanation, field and action descriptions, and screenshots visible without exposing repo paths, raw sidecars, or editorial-only implementation details.

Narrative content

Page body

What this surface does

This surface is the embedded Manage URLs modal opened from CMS Page Editor for one page key.

Operators use it to maintain the URL rows attached to the current page without leaving the page editor workspace.

Where it appears

  • parent flow: CMS Page Editor
  • surface type: modal, not a standalone route
  • page scope: one urlPageKey at a time

What operators can do here

  • review all URLs already linked to the current page
  • add a new row
  • change the locale code for a row
  • change the stored path
  • remove an existing row
  • save the full page-level URL set in one action

Row behavior

  • Add URL creates a local row with:
    • urlId: 0
    • urlLocale: any
    • urlType: direct
    • urlPageKey set to the current page key
  • The table is sorted in the FE by createdAt.
  • New unsaved rows are removed locally. Persisted rows first call DELETE /urls/:urlId.

Important caveats

  • Save URLs uses the bulk update route. New rows are created and existing rows are updated through the same PUT /urls workflow.
  • Save URLs is debounced by 1000ms before the PUT /urls request is sent.
  • Closing the modal resets the FE state back to the last loaded URL list.
  • The modal helper copy says URLs can be set as direct or redirect, but the current visible row editor only exposes Locale and URL. There is no visible control for urlType or redirect destination on this surface today.
  • Row order is sorted by createdAt inside the modal for display. It is not a ranking control and it does not change URL priority.

Validation rules

  • every row must have a URL value
  • every URL must start with /
  • URLs in the same save set must be unique
  • backend uniqueness is also enforced globally by URL path, not only per page key
  • backend validation also requires redirect records to carry urlSettings.redirect.to

Verification status

  • status: verified_backend_and_core
  • verified FE parent surface:
    • CMS Page Editor modal
  • verified core routes:
    • GET /urls?pageKey=<pageKey>
    • PUT /urls
    • DELETE /urls/:urlId
Calculation notes

Calculations

calculation

Add row defaults

Verification
verified_fe_only
Logic
`Add URL` appends a local row with `urlId: 0`, `urlLocale: any`, `urlPageKey` set to the current page key, `urlType: direct`, and empty `url`., The row is treated as unsaved until the bulk save succeeds.
calculation

Validation and duplicate guards

Verification
verified_backend_and_core
Logic
FE blocks save when any row has an empty `url`., FE blocks save when any `url` does not start with `/`., FE blocks save when duplicate `url` values exist in the current save set., Core `editURLBulk` repeats the duplicate-path guard before persisting rows.
calculation

Delete vs remove

Verification
verified_backend_and_core
Logic
Persisted rows call `DELETE /urls/:urlId` before removal from the modal state.
calculation

Save debounce and close

Verification
verified_fe_only
Logic
Submit uses a debounced save callback with `1000ms` delay., Successful save shows a success toast, clears the submitting state, and closes the modal.
calculation

Modal close reset

Verification
verified_fe_only
Logic
Modal close resets Formik state back to the last loaded `urls` payload., Closing the modal therefore discards unsaved local row edits.
calculation

Row order display

Verification
verified_fe_only
Logic
The table rows are sorted by `createdAt` for display., This is a presentation order only; the modal does not expose ranking or priority controls.
Field dictionary

Fields

field

Page Key

The CMS page key whose URL rows are being managed in this modal.

Data Type
string
field

Locale

Chooses which locale the row belongs to, or `Any` for a shared path.

Data Type
locale-code
field

URL

Stored path for this row. It must start with `/`.

Data Type
path
field

Row Identifier

Internal identifier used to decide whether the save updates an existing row or creates a new one.

Data Type
integer
Caveats
New unsaved rows start with `0` in the FE.
field

Validation Error

Blocking message shown when required values, leading slash rules, or uniqueness checks fail.

Data Type
string
Caveats
Redirect-specific validation exists in the modal schema and core routes even though redirect fields are not exposed in the current row editor.
field

Empty State

Helper panel shown when the current page has no URL rows yet.

Data Type
empty-state
Operational notes

Notes

item

The modal itself currently saves through `PUT /urls`, not through the standalone `POST /urls` route.

item

`editURLService` creates a row when the provided `urlId` does not match an existing record.

item

FE row validation enforces non-empty values, a leading slash, and uniqueness before save.

item

The visible row editor does not expose redirect-destination fields even though the schema and core validators support redirect records.

item

`Add URL` inserts a local row with `urlId: 0`, `urlLocale: any`, `urlType: direct`, and the current `pageKey`.

item

`Save URLs` is debounced by `1000ms` before the bulk `PUT /urls` request is sent.

item

Closing the modal resets form state to the last loaded `urls` payload.

item

`DELETE /urls/:urlId` is used only for persisted rows; unsaved rows are removed locally from the current FE array.

Related references

Related pages

pageURLs

Operator documentation for the URL inventory and the embedded page-level URL editor used from CMS Page Editor.

pageURLs / List

Standalone URL inventory with search, page and locale filters, FE-only ID sorting, public-link copy, and linked CMS page navigation.

pageAffiliate Deals / Form

Create and edit form for affiliate deals, including PID, date window, commercial terms, and responsible person.

pageAffiliate Payment Settings / Form

Create and edit form for one affiliate payment-setting record, with visible PID targeting, minimum deposit threshold, and active-state control.

pageAuto Tags Manager / Create

Full rule-builder for a new automatic tagging rule, including tag actions, coupon actions, KPI field selection, and draft impact estimation.

pageAutomatic Withdrawal / Form

Create and edit form for one automatic-withdrawal rule, including thresholds, KYC, countries, methods, tags, and per-currency limits.