ATK 'Beyond The Pizza Guides'

ATK beyond the Pizza Guides

ATK

Peter C. Verhage - 14th of May 2008

beyond the Pizza Guides


Node


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


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


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


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)


Meta Node


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 {}


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!


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!


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)


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


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


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


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


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


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


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)!


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)


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])”


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


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)


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)


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


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


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)


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


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


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)


Meta Policy


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!)


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


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


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



• 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



• atkExpressionAttribute

• Custom expressions in select statement

• Anything that is allowed by the database (subqueries, function calls etc.)

• Even supports sorting and limited searching



• 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!)



• 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



• 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



• 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



• 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)



• 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!



• 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)



• 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]’”);



• 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



• 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, ...);



• 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


Partials


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


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


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)


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.


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


Data Grid


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


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();


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 :)


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?

• ...?

ATK 'Beyond The Pizza Guides'

Business

Transcript of ATK 'Beyond The Pizza Guides'