ATK 'Beyond The Pizza Guides'

ATK
beyond the Pizza Guides

Peter C. Verhage - 14th of May 2008

ATK 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 modiﬁer)
• $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 ﬂags:
• 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 modiﬁcations 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)
• ﬂags (AF_OBLIGATORY, AF_PRIMARY...)
• order (in regard to other attributes)
• default value (limited!)

• Only one extends atkMetaNode {}
class Person
line of code needed:


Meta Node
• Options can be specified using:
•
protected class variables
• array in parent::__construct call (useful for base class!)

• Options: name (“people”)
•
table - table
• 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): (“[name]”)
•
descriptor - descriptor template
• index - attribute name for index (“name”)
• securityAlias - security alias (“module.node”)
• securityMap - security map (array(“publish” => “edit”))

• Be careful with inheritance!


Meta Node
• Implement metameta(atkMetaPolicy $policy)
public static function
method for more control:

• Allows full control over attributes and
relations
• Make sure it’s deﬁned 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 speciﬁed 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:

• ﬁlter - 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

• ﬁlter - 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
speciﬁed 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

• ﬁlter - destination node where clause

• type speciﬁc 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 conﬁgured 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 $conﬁg_meta_policy to set an
application wide policy
• Can be speciﬁed 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
ﬂags (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

• ﬂags - ﬂags; 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 modiﬁcations; 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 ﬁelds
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 ﬁltering 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($ﬁelds)
• $rel->setAutoCompleteSearchMode($mode)
(exact, startswith, contains)

• By default searches descriptor ﬁelds

• 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: ﬁltering (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 speciﬁcation 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 speciﬁed 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:atkDataGrid::create($node);
$grid =
$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 ﬂexible; 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'

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à ATK 'Beyond The Pizza Guides'

Similaire à ATK 'Beyond The Pizza Guides' (20)

Dernier

Dernier (20)

ATK 'Beyond The Pizza Guides'