{datovkabulk:subcommand:settings:ui:refusal}

Description

Builds the page of a site from which staff send one letter to many recipients by data box (ISDS, the Czech government messaging system). The server administrator binds the slices to an ISDS account in misc/datovka/datovka_conf.php; the page itself is an ordinary site page made of this command. The page subcommand is the gate: it reads the settings of the page, checks that the logged-in user may edit all items of the campaign slice, runs the action the page form posted (save a draft, send a test message, queue the sending, stop, continue, copy...) and only then expands the user interface. Every other subcommand reads the campaign, its recipients, messages and progress, and works only inside that interface - anywhere else it returns an empty string. So the whole interface goes into the third parameter of page, written in a deferred-evaluation block - an opening brace immediately followed by an opening parenthesis, closed by a closing parenthesis immediately followed by a closing brace - so that nothing in it expands before the gate decides. The block ends at the first such closing pair, so keep that pair out of inline JavaScript in the interface; the row templates of events, files and types go into the same kind of block. Show every view of the campaign and message slices by the view subcommand, not by a plain view command. Nothing before the gate may read those two slices: an item or view read before it is read again, but define, array, table, dictionary and the item of an enclosing item or view row keep the masked values they read, and dictionary may serve a cached copy even inside the gate. The page works only as a page of the site module of its own site, and must not be the routed page of an item of those two slices. Text values the subcommands return are already escaped for HTML - do not wrap them in safe; the same holds for the aliases the row templates of events, files and types get. _#URL of files is only for isds_remove[], never for an href or src. The letter body the campaign item stores is raw posted HTML: escape it wherever the template shows it, also inside a textarea. For developers: the full contract of each subcommand (result codes, progress states, URL parameters) is in the docblock of AA_Stringexpand_Datovkabulk in include/stringexpand.php.

Parameters

subcommand required

What the command does. page opens the sending interface; every other subcommand works only inside the interface page opened and returns an empty string anywhere else. An unknown subcommand returns an empty string.

Allowed values page - the gate, opens the interface; fields - the hidden fields of a POST form for one action (see settings and ui); env - test or production; sender - the data box the page sends from; testboxes - the test boxes, dash-separated; regbox - the box the data-box register offers for a recipient item; campaign - the campaign the page was loaded with; result - what the posted action did (text, code, status, action, charge); recipients - count, skipped, ids or skippedids of a campaign; view - a view of the campaign or message slice by its name (see ui); campaigns - ids or count of the campaigns; messages - ids or count of a group of messages; param - a known isds_ URL parameter (tab, show, step, part, list, page, q); progress - how far a sending got (state, counts, until, error...); advice - what a code means and how to go on; filter - the stored recipient filter of a campaign; source - name, box, type, member or skip reason of a recipient item; search - ids of recipient items whose name holds isds_q; message - the message given in the URL; events - the timeline of a message; files - the attachments of a campaign; types - the recipient types the page offers; letterhead - the letterhead of the settings; members - 1 when the page tells members; url - the href of a link to the page with isds_ pairs.
settings optional

The second parameter; its meaning depends on the subcommand. For page: the settings as a JSON object, best written with jsonasoc. Required: campaign_slice, message_slice, source_slice (the slice of the recipients) and types (item types with their labels, a nested jsonasoc). Optional: default_types (a list of the types chosen at first), member_field (the source field that tells a member), test_box (the test boxes), max_recipients (default 1000, at most 5000), environment (only test - production is decided by datovka_conf.php) and letterhead (plain text above the letter). An unknown key, or slices datovka_conf.php does not bind to the site, is an error: a user who may fix the settings sees what to fix, anyone else gets the refusal. For fields: the action - save, discard, clone, resume, stop, abandon, test, send, verify or fixbox; the POST form adds for save isds_subject, isds_to_hands, isds_body and, for recipients, isds_membership, isds_types[], isds_include, isds_exclude, with attachments as isds_files[] (enctype multipart/form-data) and isds_remove[]; for clone isds_scope (all, unsent or one, with one also isds_message); for test isds_box (one of testboxes); for send isds_confirm (the recipients count the page showed); for verify isds_message; for fixbox isds_recipient and isds_box from regbox; discard, resume, stop and abandon add nothing. An empty result of fields means the action is not offered now - show no form then. For the other subcommands: the campaign id of recipients, progress, filter, files and types; the item id of regbox and source; the message id of events; the code of advice; the view name of view; the group of messages; the URL parameter of param; the kind of answer of result; the link pairs of url; count for campaigns; resend for message.

ui optional

The third parameter. For page: the whole user interface of the page, in a deferred-evaluation block (see the description) so it stays unexpanded until the gate checks the user. Otherwise: the campaign id of fields (none only to save a new campaign); what to return for recipients, progress, filter, source and messages; the row template of events, files and types; run for advice of a sending error; the ids of view - it lists exactly these, in their order, and none when there are none. The view name must be isdscampainer (the entry view) or begin with isds_, and the view must belong to the campaign or message slice; any other name, a name two of their views share, or a view of another slice shows nothing. In the view settings (fourth parameter) listlen, sort, group_by, from, to and page are ignored.

refusal optional

The fourth parameter. For page: the text shown instead of the interface to a visitor who is not logged in or may not edit all items of the campaign slice - also when the page is not rendered by the site module of its own site, and when the settings are wrong, except to a user who may fix them. For view: the settings of the view, as in the view command.

Examples

test[{datovkabulk:env}]
Expected[]
Actual[]
env tells test or production, but only inside the interface the page subcommand opened. This documentation page is no sending page, so the result is empty - the brackets make it visible. Every subcommand except page behaves the same way here.
test[{datovkabulk:param:step}]
Expected[]
Actual[]
param returns a known isds_ parameter of the page URL - step is test, send, search or files; an unknown value gives an empty string. Outside the interface it is empty even when the URL holds the parameter. Branch on param, never on the raw URL.
test[{datovkabulk:nosuch}]
Expected[]
Actual[]
A subcommand the command does not know returns an empty string, with no error.
virtual{datovkabulk:env}
Expected(test or production - inside the interface opened by the page subcommand)
Illustrative: within the user interface of the page the answer tells whether datovka_conf.php binds the slices to the test or the production environment of ISDS. A template typically shows a warning banner for test.
virtual{ifeq:{datovkabulk:result:status}:refused:<p class=error>{datovkabulk:result}</p>}
Expected(the reason, as a paragraph - after a posted action the gate refused, inside the interface)
Illustrative: after an action the page loads again with isds_campaign and isds_r in its URL; result returns the text to read (default), its code, status (done, refused, busy, expired, failed), action or charge. The result shows for 10 minutes.
test{jsonasoc:campaign_slice:aaaabbbbccccddddeeeeffff00001111:message_slice:aaaabbbbccccddddeeeeffff00002222:source_slice:aaaabbbbccccddddeeeeffff00003333:types:{jsonasoc:mesto:Cities}:max_recipients:1000}
Expected{"campaign_slice":"aaaabbbbccccddddeeeeffff00001111","message_slice":"aaaabbbbccccddddeeeeffff00002222","source_slice":"aaaabbbbccccddddeeeeffff00003333","types":"{\"mesto\":\"Cities\"}","max_recipients":"1000"}
Actual{"campaign_slice":"aaaabbbbccccddddeeeeffff00001111","message_slice":"aaaabbbbccccddddeeeeffff00002222","source_slice":"aaaabbbbccccddddeeeeffff00003333","types":"{\"mesto\":\"Cities\"}","max_recipients":"1000"}
The settings the page subcommand takes as its second parameter, built with jsonasoc: the three slices and types are required, the rest optional. A nested jsonasoc arrives as its JSON text - the page reads types that way. This example only builds the JSON: the page subcommand itself is not run here, because its output would depend on who views the page - a user who may fix the settings would see the list of problems, others the refusal - and it would switch off the page cache and write a log row once a day.