{newitem:template_long_item_id:field_1:new_value_1:field_2:new_value_2:...}

Description

Creates a new item by copying a template item and applying field/value pairs, then returns the new item ID. The first argument is the ID of the template item to copy (a 32-character item ID); the remaining arguments are field-id and value pairs that overwrite fields in the copy. If the first argument is empty or not a valid 32-character ID, newitem does nothing and returns an empty string (it warns No template id) - so an empty or invalid template is a safe no-op. The template must live in a slice related to the current slice (or the current slice itself); otherwise newitem warns No related slice found and returns empty. If the template ID is well-formed but matches no existing item, nothing is created and the result is empty. On success the copy is set active with an empty seo field and newitem returns its new ID. Single values are plain text; multi-values are written as JSON arrays. Append a plus sign to a field ID (field........+) to ADD the value instead of replacing it. Because newitem writes to the database it is never cached and it runs on every render - so any live template (such as a fixture in a related slice) would be cloned each time the page is shown. Use a found ID with ensureitem for lookup-or-create, and updateitem to change an existing item. newitem never updates an existing item.

Parameters

template_long_item_id required default (none)

ID of the template item to copy. It must be a valid 32-character item ID and the template must live in a slice related to the current slice (or the current slice itself). The new item inherits the template field values, except seo (cleared) and status_code (set active). If this argument is empty or not a valid ID, newitem does nothing and returns an empty string; if it is well-formed but matches no existing item, nothing is created and the result is also empty.

field_id optional default (none)

A field ID (16 characters, for example headline........) whose value to set on the new copy. Append a plus sign (relation........+) to ADD the value instead of replacing it. Field and value arguments come in pairs and may repeat. Optional - omit all pairs to copy the template unchanged.

new_value optional default (none)

The value for the preceding field_id. A single value is plain text; multiple values are written as a JSON array, for example ["enviro","social"]. Paired with field_id and repeatable.

Examples

virtual[{newitem:00000000000000000000000000000000:relation........+:c239cb267837a25b4efb5892ca4f4324}]
Expected(the 32-character ID of the newly created item)
Actual[]
Append a plus sign to a field ID to ADD the value to that field rather than overwrite it - useful for relation fields that link several items. Here the new copy keeps its template relations and gains one more. As above the all-zero template keeps this a no-op on the page; the result with a real template would be the new items ID.
virtual[{newitem:00000000000000000000000000000000:headline........:New article:category........:["news"]}]
Expected(the 32-character ID of the newly created item, e.g. c239cb267837a25b4efb5892ca4f4324)
Actual[]
The real-world shape: the first argument is the template item ID to copy, then field-id and value pairs that overwrite fields in the copy. headline........ gets a single text value; category........ takes a JSON array because it can hold several values. On success newitem returns the new items ID. This example uses an all-zero template so it stays a no-op on this page (the displayed result is empty); with a real template in a related slice it would create one item on every render, which is why this is illustrative, not a live test.
virtual{define:found:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-headline........-==-Gamma}}{ifset:{var:found}:Reusing {var:found}:{newitem:00000000000000000000000000000000:headline........:Gamma}}
Expected(Reusing the found Gamma item ID when it exists; otherwise the new items ID)
ActualReusing 5726c2c6b035d7aab450d1794e9e90d7
The standard pattern: first look for an existing item with ids, then create one only when the search found nothing. ifset runs the newitem branch only on a miss, so a matching item is reused and the database is written at most once. Because the create branch would write, this is illustrative; in production the template is a real holding item and the search keys on your own field (for example a user ID or a slug).
test[{newitem:}]
Expected[]
Actual[]
With no template ID, newitem does nothing and returns an empty string (it warns No template id). Nothing is created. This makes newitem safe to call conditionally: pass an empty first argument when you do not want to create an item.
test[{newitem:not-a-real-id}]
Expected[]
Actual[]
The template ID must be exactly 32 hexadecimal characters. Anything else (here a plain word) fails the ID check, so newitem creates nothing and returns an empty string.
test[{newitem:00000000000000000000000000000000}]
Expected[]
Actual[]
The ID is well-formed (32 hex characters) but matches no item in any related slice, so there is nothing to copy. newitem creates nothing and returns an empty string - no write happens.
← All expressions