atk 'beyond the pizza guides
DESCRIPTION
Presentation on some of the more advanced features of the ATK frameworkTRANSCRIPT
ATK beyond the Pizza Guides
ATK
Peter C. Verhage - 14th of May 2008
beyond the Pizza Guides
ATK beyond the Pizza Guides
Node
ATK beyond the Pizza Guides
Node
• Action triggers:
• preAdd(&$record) / postAdd($record)
• preUpdate(&$record) / postUpdate($record)
• preDelete($record) / postDelete($record)
• preCopy(&$record)
• Return false to abort action (auto rollback)
• Most of the time implemented inside node
ATK beyond the Pizza Guides
Node
• Implement triggers outside a node using a listener (registered using a modifier)
• $node->addListener(...)
• atkActionListener - deprecated
• atkTriggerListener - allows you to implement all previously mentioned triggers inside your own external class with the same behavior
ATK beyond the Pizza Guides
Node
• Less known flags:
• NF_TRACK_CHANGES - gives access to the original record for update actions ($record[‘atkorgrec’])
• NF_ADDAFTERADD - allows adding record after record
• NF_ADD_DIALOG - add new records inside a dialog
• NF_ADDORCOPY_DIALOG - shows a dialog when wanting to add a new record giving the user the choice to copy an existing record or add a new record
ATK beyond the Pizza Guides
Node
• Misc. useful methods:
• $node->setDescriptorTemplate($template) - no need to implement descriptor_def anymore
• $node->preAddToEditArray(&$record, $mode) - allows you to do last minute modifications to attributes etc. just before a record is edited
• $node->text(...) - context aware translations
• $node->escapeSQL(...) - database aware escaping (knows the database your node uses)
ATK beyond the Pizza Guides
Meta Node
ATK beyond the Pizza Guides
Meta Node
• Uses database metadata to detect:• table and sequence name
• attributes:
• name
• type (e.g. date → atkDateAttribute)
• flags (AF_OBLIGATORY, AF_PRIMARY...)
• order (in regard to other attributes)
• default value (limited!)
• Only one line of code needed: class Person extends atkMetaNode {}
ATK beyond the Pizza Guides
Meta Node
• Options can be specified using:• protected class variables
• array in parent::__construct call (useful for base class!)
• Options:• table - table name (“people”)
• sequence - sequence name (“seq_person”)
• db/database - database name (“default”)
• flags - node flags (NF_ADD_LINK etc.) use an array for multiple flags!
ATK beyond the Pizza Guides
Meta Node
• Options (continued):• descriptor - descriptor template (“[name]”)
• index - attribute name for index (“name”)
• securityAlias - security alias (“module.node”)
• securityMap - security map (array(“publish” => “edit”))
• Be careful with inheritance!
ATK beyond the Pizza Guides
Meta Node
• Implement meta method for more control:public static function meta(atkMetaPolicy $policy)
• Allows full control over attributes and relations
• Make sure it’s defined static to let the caching mechanism kick in!
• Make full use of inheritance by calling parent::meta($policy)
ATK beyond the Pizza Guides
Meta Node
• Control which columns to expose:
• $policy->setExcludes($attr1, $attr2, ...) - exclude certain attributes
• $policy->setIncludes($attr1, $attr2, ...) - only include the given attributes, implicitly sets the attribute order!
• $policy->remove($attr) - removes a single attribute
ATK beyond the Pizza Guides
Meta Node
• Control attribute flags:
• $policy->addFlags($attr1, $attr2, ..., $flags) - add the given flag(s) for the given attributes
• $policy->removeFlags($attr1, $attr2, ..., $flags) - remove the given flags(s) for the given attributes
• $policy->setFlags($attr1, $attr2, ..., $flags) - explicitly set the flags for the given attributes (dangerous!)
• Alternatives:$policy->addFlag, $policy->removeFlag
ATK beyond the Pizza Guides
Meta Node
• Control attribute tabs/sections:
• $policy->setSections($attr1, $attr2, ..., $sections) - sets the tabs/sections for the given attributes
• $sections can be either a single tab/section name or an array of tab/section names
• Format: <tab> or <tab>.<section>
• Previously set tabs/sections will be ignored!
• Alternatives: $policy->setSection, $policy->setTabs, $policy->setTab
ATK beyond the Pizza Guides
Meta Node
• Forcing insertion/updates:
• $policy->addForceInsert($attr1, $attr2, ...) - set force insert to true for the given attributes
• $policy->removeForceInsert($attr1, $attr2, ...) - don’t force insertion of the given attributes
• $policy->addForceUpdate($attr1, $attr2, ...) - set force update to true for the given attributes
• $policy->removeForceUpdate($attr1, $attr2, ...) - don’t force update of the given attributes
ATK beyond the Pizza Guides
Meta Node
• Changing attribute types and parameters:
• $policy->setType($attr, $type, $param1, ...) - sets the attribute type for the given attribute(s) and uses the given parameters when constructing the attribute
• $attr can be a single attribute name or an array
• $type can be anything that is valid for useattrib, userelation or atkimport (and knows about the node’s module)
• Parameters (optional) are passed as extra arguments
ATK beyond the Pizza Guides
Meta Node
• Changing attribute types and parameters (alternative):
• $policy->setTypeAndParams($attr, $type, $params) - sets the attribute type for the given attribute(s) and uses the given parameters when constructing the attribute
• Same as $policy->setType, but parameters are passed as a single array and not as separate arguments
ATK beyond the Pizza Guides
Meta Node
• Adding / overwriting attributes:
• $policy->add($name, $type [, $params [, $flags]])
• $type can be anything that is valid for useattrib, userelation or atkimport (and knows about the node’s module)
• $params should contain an array of attribute parameters (at least all mandatory parameters!)
• $flags should contain the attribute flags (int)
• Overwrite the current attribute entry (if applicable)!
ATK beyond the Pizza Guides
Meta Node
• Many-to-one relation:
• $policy->hasOne($accessor)
• $accessor is the destination node
• Format: <module>.<node>
• If part of the same module, module can be ommitted
• Automatic translation from singular accessor names to plural node names (e.g. person → people)
ATK beyond the Pizza Guides
Meta Node
• Many-to-one relation (continued...):
• Local attribute name is automatically detected (tries mutiple variants based on the destination node name and module name e.g. people_id, person_id, people, person etc.)
• $policy->hasOne($accessor, $descriptor)
• Descriptor can be specified as second parameter (overrides default descriptor in destination node)
• Format: “[name] ([city])”
ATK beyond the Pizza Guides
Meta Node
• Many-to-one relation (continued...):
• $policy->hasOne($accessor, [$descriptor,] $options)
• Options can be specified as 2nd or 3rd argument (depending on whatever a descriptor is specified)
• Array containing the following options (all optional):
• source - local attribute name
• filter - destination where clause
• large - true/false, sets the AF_LARGE flag
ATK beyond the Pizza Guides
Meta Node
• One-to-one relation
• $policy->hasOne($accessor [, $options])
• Uses same method as many-to-one relation
• Difference detected based on availability of local attribute (if not available → 1:1)
• Options:
• filter - destination where clause
• dest(-ination) - destination node attribute (forces 1:1)
ATK beyond the Pizza Guides
Meta Node
• One-to-many relation:
• $policy->hasMany($accessor [, $options])
• $accessor is the destination node
• Format: <module>.<node>
• If part of the same module, module can be ommitted
• Automatic translation from plural accessor names to singular node names (e.g. people → person)
ATK beyond the Pizza Guides
Meta Node
• One-to-many relation (continued...):
• Destination attribute name is automatically detected (tries mutiple variants based on the local node name and module name e.g. departments_id, department_id, departments, department etc.)
• Possible options ($options array):
• dest(-ination) - name of the attribute in the destination node for this relation
• filter - destination node where clause
• name - local attribute name for relation
ATK beyond the Pizza Guides
Meta Node
• Many-to-many relation:
• $policy->hasMany($accessor [, $descriptor], $options)
• Uses same method as one-to-many relation
• Descriptor is optional (if ommitted options need to be specified as second argument)
• Mandatory option “through” is used to detect that this is a many-to-many relation and should contain an accessor name for the link node
ATK beyond the Pizza Guides
Meta Node
• Many-to-many relation (continued...):
• Example: $policy->hasMany(“people”, array(“through” => “department_person”))
• Other options:
• type - display type: shuttle (default), bool(-ean), list, select, eshuttle (extended shuttle)
• local / remote - link node local / remote key
• filter - destination node where clause
• type specific options (cols/columns, rows)
ATK beyond the Pizza Guides
Meta Node
• Misc. methods:
• $policy->setOrder($attr1, $attr2, ...) - sets the order of the attributes, all attributes not mentioned will keep their current order but are placed after the explicitly mentioned attributes
• $policy->setDefaultValue($attr1, $attr2, ..., $value) - sets the initial value for the given attributes
• $policy->text($string) - same as atktext but keeps module and node type into account
ATK beyond the Pizza Guides
Meta Node
• More control needed?
• public function postMeta()
• Called after node has been configured and attributes/relations have been added
• Early enough to do some more customizations
ATK beyond the Pizza Guides
Meta Node
• Configuration options:
• $config_meta_caching - controls whatever generated code for meta nodes should be cached or not, turn of during development!
• $config_meta_policy - can be used to set an application wide alternative for the default policy class
• $config_meta_compiler - allows customization of the meta policy compiler (only useful in rare cases)
• $config_meta_grammar - allows customization of the singular / plural grammar rules (person → people)
ATK beyond the Pizza Guides
Meta Policy
ATK beyond the Pizza Guides
Meta Policy
• Responsible for detecting the defaults for a meta node (table, attributes etc.)
• Can be subclassed for supporting your own set of rules
• Use $config_meta_policy to set an application wide policy
• Can be specified per node using the $metaPolicy option (or in base class!)
ATK beyond the Pizza Guides
Meta Policy
• Customizable methods:
• _getTypeAndParams($name, $meta) - should return an array with key “type” and “params” containing the attribute type and array of parameters
• _getFlags($name, $meta) - should return the attribute flags (int)
• _getOrder($name, $meta) - should return the order (index) for the attribute
• _getDefaultValue($name, $meta) - should return the default value for the attribute
ATK beyond the Pizza Guides
Meta Policy
• Customizable methods (continued...):
• $name contains the column name
• $meta contains the column metadata and consists of:
• gentype - generic data type
• num - column index
• flags - flags; MF_PRIMARY, MF_NOT_NULL etc.
• default - detected default value
ATK beyond the Pizza Guides
Attributes and relations
ATK beyond the Pizza Guides
Attributes and relations
• ATK contains:
• More than 50 attributes
• More than 10 relations
• Still growing each day
• Luckily they are pretty well named :)
• Some highlights of less known attributes, relations and features you probably don’t know about
ATK beyond the Pizza Guides
Attributes and relations
• Tracking of modifications; who / when
• Attributes:• atkCreatedByAttribute - added by user ...
• atkCreateStampAttribute - created at
• atkUpdatedByAttribute - last updated by user ...
• atkUpdateStampAttribute - last updated at
• Automatically used by meta node for fields with correct type and name: created_by, created_at, updated_by, updated_at
ATK beyond the Pizza Guides
Attributes and relations
• atkExpressionAttribute
• Custom expressions in select statement
• Anything that is allowed by the database (subqueries, function calls etc.)
• Even supports sorting and limited searching
ATK beyond the Pizza Guides
Attributes and relations
• atkTabbedPane
• Allows you to created nested tabs
• Simply name the attributes you want to show on each tab
• Attributes are automatically “removed” from their normal position
• Use carefully (keep interface simple!)
ATK beyond the Pizza Guides
Attributes and relations
• atkRadioDetailsAttribute
• Allows you to show detail selections based on radio button selections
• Works similar to atkTabbedPane
• Still has some rough edges but will be improved in the near future
ATK beyond the Pizza Guides
Attributes and relations
• Many many-to-many relations:
• atkManyBoolRelation - checkboxes
• atkShuttleRelation - move items between two lists
• atkExtendableShuttleRelation - allows filtering of shuttle lists (will eventually supersede atkShuttleRelation)
• atkManyToManySelectRelation - multi select list
• atkManyToManyListRelation - add items one by one using auto-completion or drop-down
ATK beyond the Pizza Guides
Attributes and relations
• atkManyToOneRelation auto-completion
• AF_MANYTOONE_AUTOCOMPLETE
• Many options:• $rel->setAutoCompleteMinRecords($recs)
• $rel->setAutoCompleteCaseSensitive($value)
• $rel->setAutoCompleteSearchFields($fields)
• $rel->setAutoCompleteSearchMode($mode) (exact, startswith, contains)
• By default searches descriptor fields
ATK beyond the Pizza Guides
Attributes and relations
• Showing more than one column for an atkManyToOneRelation in list view
• $rel->addListColumn($col) or $rel->addListColumns($col1, $col2, ...)
• Allows full sorting and searching
• Only want to show extra columns?• AF_HIDE_LIST
• $rel->setAlwaysShowListColumns(true)
ATK beyond the Pizza Guides
Attributes and relations
• Use a dialog for adding new records to an atkOneToManyRelation
• AF_ONETOMANY_ADD_DIALOG or AF_ONETOMANY_ADDORCOPY_DIALOG
• Only useful for simple destination nodes
• Doesn’t work for destinations containing one or more atkFileAttributes!
ATK beyond the Pizza Guides
Attributes and relations
• Ever wanted to use a normal attribute without having it query the database?
• $attr->setLoadType(NOLOAD)
• $attr>setStorageType(NOSTORE)
• Example usage: filtering (using dependencies, see next slide)
ATK beyond the Pizza Guides
Attributes and relations
• Sometimes selections should change based on other attribute values
• $a->addDependee($b)
• If A changes B is automatically reloaded
• Common scenario: $b = $this->add(new atkManyToOneRelation(‘b’, ...));$b->setDestinationFilter(“column = ‘[a]’”);
ATK beyond the Pizza Guides
Attributes and relations
• Sometimes you only want to show certain attributes based on certain conditions
• $attr->setInitialHidden(...)
• Adds a special class “atkAttrRowHidden” to the attribute’s table row
• Use JavaScript to show/hide attribute row on demand by adding/removing this class
ATK beyond the Pizza Guides
Attributes and relations
• Next to tabs, attributes can also be placed in expandable/collapsable sections
• Specify a section next to the tab name:
• $node->add(..., “tab.section”)
• $policy->setSection($attr1, $attr2, “tab.section”)
• To expand sections by default:$node->addDefaultExpandedSections($section, ...);
ATK beyond the Pizza Guides
Attributes and relations
• Misc. useful methods:
• $attr->text(...) - context aware translation
• $attr->escapeSQL(...) - database aware escaping (knows the database the attribute’s node is using)
• $attr->setForceInsert(...) - force insert even though the attribute might be read-only
• $attr->setForceUpdate(...) - force update even though the attribute might be read-only
ATK beyond the Pizza Guides
Partials
ATK beyond the Pizza Guides
Partials
• Little snippets for (usually) Ajax requests
• Special request parameter “atkpartial” allows specification of partial name.
• ATK automatically knows not to output a full blown page for the registered output
• URLs should be built using partial_url
ATK beyond the Pizza Guides
Partials
• Interpretation of partial name depends on action handler
• In your own action handler you are free to do whatever you want
• Best practice: call $handler->partial(...)
• Searches for “partial_<name>” method inside handler
ATK beyond the Pizza Guides
Partials
• atkAddHandler / atkEditHandler allow handling of partials by attributes
• Partial name: “attribute.<name>.<partial>”
• Retrieves attribute with specified name and calls method “partial_<name>”
• Method can then return the necessary HTML or other output (e.g. JSON)
ATK beyond the Pizza Guides
Partials
• Used for dependency mechanism between attributes (atkAttribute contains special “partial_refresh” method)
• Used for auto-completion mechanism in atkManyToOneRelation
• Used for addition dialog mechanism in atkOneToManyRelation
• Etc.
ATK beyond the Pizza Guides
Partials
• Always use atkPage to register JavaScript code and stylesheets
• ATK makes sure, even for partials, that the JavaScript code gets loaded and executed and that stylesheets get registered (when needed)
• Same mechanism is used to append extra debug information for partial requests
ATK beyond the Pizza Guides
Data Grid
ATK beyond the Pizza Guides
Data Grid
• Replaces the record list
• Uses Ajax to update its contents
• Easy to use, only a few lines of code
• Easy to extend using components
• Can be easily mixed with other instances on the same page
ATK beyond the Pizza Guides
Data Grid
• Usage:$grid = atkDataGrid::create($node);$result = $grid->render();
• Calls the current action with “atkpartial” set to “datagrid” for updates
• Updates implemented using:$grid = atkDataGrid::resume($node);$result = $grid->render();
ATK beyond the Pizza Guides
Data Grid
• Way too many options to mention here
• Very flexible; allows you to set almost anything from its name to which URL should be called for updates to which components to use to render the grid etc.
• Well documented code, so please check the generated docs and the code itself
• Don’t blame me for the atkDGList contents :)
ATK beyond the Pizza Guides
Data Grid
• Future goals:
• In-line editing (available as quick hack in separate branch, not for production!)
• Better separation of code and markup (especially for list component)
• Sortable rows?
• ...?