API Snap Cards

Caligrafy\Snap\Cards

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

Part of Snap.

namespace Caligrafy\Snap;

class Cards

Source: framework/core/Snap/Cards.php:22

Snap Cards (2.23.0): every card is built from what a capability already declares

Families and types (marketing names the family with the type):

Ask: Form, Choice, Confirm   Show: Answer, List   Go: Shortcut   Track: Task   Offer: Suggestion, Routine

Phase 1 builds Ask: Form, Ask: Choice, Show: Answer and Show: List from:

• the capability's rules and descriptions (fields, types, limits, choices, required)
• the shape of its result (a page, a list, a record, a value)
• optional hints in application/config/snap.php (Snap\Hints)

The model, later, only picks a card and fills it; it never invents a card's structure.

Constants

• VERSION = 1
• MAX_OPTIONS = 50
• THING_ICONS = ...
• VERB_ICONS = ...
• FIELD_ICONS = ...
• MAX_COLUMNS = 5
• LONG_TEXT = 140
• HIDDEN = '/^(snap_|notify_|queue_work$)/'

Public properties

• public static $path = '/snap': string where Route::snap() serves the cards ('/snap' by default)

Methods

• Cards::ask()
• Cards::show()
• Cards::confirm()
• Cards::forget()
• Cards::needsInput()
• Cards::notice()
• Cards::catalog()
• Cards::fields()
• Cards::url()
• Cards::applies()
• Cards::name()
• Cards::risk()
• Cards::icon()
• Cards::title()
• Cards::plural()
• Cards::singular()

Cards::ask()

public static function ask(
    $name,
    Context $context,
    array $values = array(),
    array $errors = array(),
    $message = null,
    $asForm = false
)

The card that asks for a capability's inputs: Ask: Form, or Ask: Choice when one pick is all that is missing

Parameters

• $name
• $context Context
• $values array, default array(): inputs already known (prefilled)
• $errors array, default array(): field => message, from a refused call
• $message, default null
• $asForm, default false

Source: framework/core/Snap/Cards.php:47

Cards::show()

public static function show($name, $result, array $input, Context $context)

The card that shows a capability's result: Show: List for many rows, Show: Answer for one record or a value

Parameters

• $name
• $result
• $input array
• $context Context

Source: framework/core/Snap/Cards.php:96

Cards::confirm()

public static function confirm(
    $name,
    Context $context,
    array $inputs,
    $token,
    array $changes,
    $subject,
    $risk,
    $undoable,
    $message = null
)

Ask: Confirm: what a change will do, before it runs (phase 2). The token is the person's consent once they click; the card's address never carries it.

Parameters

• $name
• $context Context
• $inputs array
• $token
• $changes array: [label, before?, after] lines
• $subject
• $risk
• $undoable
• $message, default null

Source: framework/core/Snap/Cards.php:155

Cards::forget()

public static function forget()

Forgets the choices read in this request (after a change, so the next card shows what is true now)

Source: framework/core/Snap/Cards.php:192

Cards::needsInput()

public static function needsInput(array $ask, array $inputs)

Whether an Ask card still needs the person: a required input is missing, or only the id of a thing to change was given (an update_ starts as its form). A delete needs nothing more than its id.

Parameters

• $ask array
• $inputs array

Source: framework/core/Snap/Cards.php:202

Cards::notice()

public static function notice($name, $message, $kind = 'info', array $inputs = array())

A message instead of a result: a refusal that is not about the inputs (not found, conflict, forbidden)

Parameters

• $name
• $message
• $kind, default 'info'
• $inputs array, default array()

Source: framework/core/Snap/Cards.php:220

Cards::catalog()

public static function catalog(Context $context, $run = true)

Every capability this person may use, as the card it starts with (the gallery of phase 1)

Parameters

• $context Context
• $run, default true

Source: framework/core/Snap/Cards.php:234

Cards::fields()

public static function fields($name, Context $context, array $values = array(), ?array $hints = null)

The fields of an Ask card, from the rules: widget, limits, options, label, help, current value

Parameters

• $name
• $context Context
• $values array, default array()
• $hints ?array, default null

Source: framework/core/Snap/Cards.php:259

Cards::url()

public static function url($name, array $input = array())

No doc comment.

Parameters

• $name
• $input array, default array()

Source: framework/core/Snap/Cards.php:335

Cards::applies()

public static function applies($name, array $record, Context $context)

Whether an action applies to a record now, from its hint 'applies':

'in' => array('capability' => 'list_loans', 'field' => 'book_id')       the record is in that list
'not_in' => array(...)                                                 the record is not in that list

The list is read as the person (once per request); one they may not read leaves the action out.

Parameters

• $name
• $record array
• $context Context

Source: framework/core/Snap/Cards.php:572

Cards::name()

public static function name(array $record)

What a record is called: its own title or name, else the title or name of the record it is about (a loan is about its book), else its username, else #id

Parameters

• $record array

Source: framework/core/Snap/Cards.php:600

Cards::risk()

public static function risk($capability)

No doc comment.

Parameters

• $capability

Source: framework/core/Snap/Cards.php:620

Cards::icon()

public static function icon($name)

No doc comment.

Parameters

• $name

Source: framework/core/Snap/Cards.php:633

Cards::title()

public static function title($name)

No doc comment.

Parameters

• $name

Source: framework/core/Snap/Cards.php:646

Cards::plural()

public static function plural($word)

No doc comment.

Parameters

• $word

Source: framework/core/Snap/Cards.php:699

Cards::singular()

public static function singular($word)

No doc comment.

Parameters

• $word

Source: framework/core/Snap/Cards.php:704