Migration from 1.16 to 1.17

This page describes all changes to your current code to update your APF installation from 1.16 to 1.17.

1. Renaming of tag classes

Due to the new tag definition concept introduced in version 1.16 naming of tag classes and reusability has been improved significantly. XML prefix and name can now be choosen freely and tags can be reused within different tag hierarchies. This fact has been used to optimize the naming of tag classes in 1.17.

Updating to release 1.17 all classes noted within the subsequent chapters must be renamed. The following chapters therefor list all naming changes according to relevance and area. In case you have implemented custom tags or components renaming is very important. In case you only use standard tags and components, renaming may not apply to your project.

The present chapter lists the changes that must be done updating to the new version imperatively.

One important pre-condition is to apply all steps of the release 1.16 migration documentation (see Migration from 1.15 to 1.16).

This is necessary, because the fallback mechanism supporting old <core:addtaglib/> tag declarations introduced in 1.16 has been removed in 1.17. The tag now expects exactly the 4 attributes namespace, class, prefix, and name.

1.1. Tags within the core namespace

The following changes to the core namespace can be applied by search&replace:

Old class name New class name
core_taglib_addtaglib AddTaglibTag
core_taglib_importdesign ImportTemplateTag
core_taglib_appendnode AppendNodeTag
html_taglib_template TemplateTag
html_taglib_placeholder PlaceHolderTag
html_taglib_getstring LanguageLabelTag
html_taglib_getstring LanguageLabelTag

Moreover, core_taglib_appendnode has been integrated into the pagecontroller.php file. For this reason, no extra <core:addtaglib/> statement is necessary with release 1.17.

1.2. Tags within the tools namespace

Within the tools namespace the following changes can ve applied using search&replace:

Old class name New class name
a_taglib_getstring LinkLanguageLabelTag
html_taglib_a HtmlLinkTag
ui_mediastream / html_taglib_mediastream / template_taglib_mediastream MediaInclusionTag
media_taglib_getstring UmgtMediaInclusionLanguageLabelTag
doc_taglib_createobject CreateDocumentFromFileTag
fcon_taglib_importdesign FrontControllerImportTemplateTag
generic_taglib_importdesign GenericImportTemplateTag
html_taglib_fallbackimport FallbackImportTemplateTag
lang_taglib_importdesign LanguageDependentIncParamImportTemplateTag
lngtmpl_taglib_importdesign LanguageDependentImportTemplateTag
html_taglib_iterator HtmlIteratorTag
iterator_taglib_item HtmlIteratorItemTag
Please note, that MediaInclusionTag can be now directly used compared to the ui_mediastream tag within version 1.16 that was an abstract class.

Regarding the APF form support, the following classes have been renamed:

Old class name New class name
form_control AbstractFormControl
html_taglib_form HtmlFormTag
form_taglib_addfilter AddFormControlFilterTag
form_taglib_addvalidator AddFormControlValidatorTag
button_taglib_getstring ButtonLanguageLabelTag
form_taglib_button ButtonTag
form_taglib_checkbox CheckBoxTag
form_taglib_csrfhash CsrfProtectionHashTag
form_taglib_date DateSelectorTag
form_taglib_marker DynamicFormElementMarkerTag
form_taglib_file FileUploadTag
form_taglib_addtaglib FormAddTaglibTag
form_control_observer FormControlObserverBase
form_taglib_error FormErrorDisplayTag
form_getstring FormLanguageLabelTag
form_taglib_placeholder FormPlaceHolderTag
form_taglib_success FormSuccessDisplayTag
form_taglib_hidden HiddenFieldTag
form_taglib_imagebutton ImageButtonTag
form_taglib_multiselect MultiSelectBoxTag
form_taglib_password PasswordFieldTag
form_taglib_radio RadioButtonTag
form_taglib_reset ResetButtonTag
form_taglib_select SelectBoxTag
select_taglib_group SelectBoxGroupTag
select_taglib_option SelectBoxOptionTag
form_taglib_area TextAreaTag
form_taglib_text TextFieldTag
form_taglib_timecaptcha TimeCaptchaTag
form_taglib_time TimeSelectorTag
form_taglib_listener ValidationListenerTag
form_taglib_multifileupload MultiFileUploadTag
form_taglib_mediastream FormMediaInclusionTag
Please note, that FormLanguageLabelTag can be now directly used compared to the ui_getstring tag within version 1.16 that was an abstract class.
In order to create custom for controls, please extend AbstractFormControl or implement the FormControl interface as of 1.17. This ensures, that they are well prepared for usage with the APF form support.

1.3. Tags within the modules namespace

Within the modules namespace the following classes have been renamed:

Old class name New class name
umgt_taglib_importdesign UmgtImportTemplateTag
umgt_taglib_logoutlink UmgtLogoutLinkTag
umgt_taglib_template UmgtTemplateTag
umgt_taglib_includecss UmgtIncludeCssTag
umgt_taglib_media UmgtMediaInclusionTag
social_taglib_bookmark SocialBookmarkBarTag
form_taglib_langlabel GuestbookFormLanguageLabelTag
gb_taglib_import GuestbookImportTemplateTag
form_taglib_captcha SimpleCaptchaTag

1.4. Tags within the extensions namespace

Renaming has been applied to the APF extensions in 1.17 as well. Please refer to the following table to get an overview of the new class names:

Old class name New class name
news_taglib_media NewsMediaInclusionTag
form_taglib_addclientvalidator AddFormControlClientValidatorTag
form_taglib_clientlistener ClientValidationListenerTag
form_taglib_clienterror FormClientErrorDisplayTag
form_taglib_getclientvalidator GetClientFormValidationTag
html_taglib_addforwardmessage AddForwardMessageTag
html_taglib_getforwardmessages DisplayForwardMessagesTag
htmlheader_taglib_gethead HtmlHeaderGetHeadTag
htmlheader_taglib_getbodyjs HtmlHeaderGetBodyJsTag
htmlheader_taglib_addcss HtmlHeaderAddCssTag
htmlheader_taglib_addcsscontent HtmlHeaderAddCssContentTag
htmlheader_taglib_addcssimage HtmlHeaderAddCssImageTag
htmlheader_taglib_addjs HtmlHeaderAddJsTags
htmlheader_taglib_addjscontent HtmlHeaderAddJsContentTag
htmlheader_taglib_addmeta HtmlHeaderAddMetaTag
htmlheader_taglib_addpackage HtmlHeaderAddPackageTag
htmlheader_taglib_addstaticcss HtmlHeaderAddStaticCssTag
htmlheader_taglib_addstaticjs HtmlHeaderAddStaticJsTag
htmlheader_taglib_addtitle HtmlHeaderAddTitleTag
Allgemeine Form: SMS*Taglib SMS*Tag

2. Renaming of common classes

base_controller has been renamed to BaseDocumentController in order to support UCC naming scheme for controller classes.

2.1. Controllers within the extensions::apfelsms namespace

Old class name New class name
SMSBreadcrumbNavTaglibController SMSBreadcrumbNavTagController
SMSNavTaglibController SMSNavTagController

3. Deletion of classes

iteratorBaseController has been deleted and the functionally is now fully integrated with the BaseDocumentController. In case you are using the iterator tag (see Special-tags) please remove the dependency to the iteratorBaseController and replace it by the BaseDocumentController. The method getIterator() is as it was before release 1.17.

4. Renaming or methods and variables

Besides the renaming of tag classes old-school or deprecated namings of methods or class variables have been removed with release 1.17. Please refer to the subsequent list to see what has been changes:

4.1. Renamed methods

Old method name New method name
AbstractFormControl::__presetValue() AbstractFormControl::presetValue()
Document::__loadContentFromFile() Document::loadContentFromFile()
Document::__extractDocumentController() Document::extractDocumentController()
Document::__extractTagLibTags() Document::extractTagLibTags()
Please note, that __loadContentFromFile()/loadContentFromFile() and __extractTagLibTags()/extractTagLibTags() are considered central methods of the APF parser. Please ensure, that these methods are renamed during migration within your custom tags.

4.2. Renamed variables

Old variable name New variable name
APFObject::$__Attributes APFObject::$attributes
APFObject::$__Context APFObject::$context
APFObject::$__Language APFObject::$language
Document::$__ObjectID Document::$objectId
Document::$__ParentObject Document::$parentObject
Document::$__Content Document::$content
Document::$__TagLibs Document::$tagLibs
Document::$__Children Document::$children
BaseDocumentController::$__Document BaseDocumentController::$document
AbstractFormFilter::$__Control AbstractFormFilter::$control
AbstractFormFilter::$__Button AbstractFormFilter::$button
AbstractFormControl::$__ControlIsValid AbstractFormControl::$controlIsValid
AbstractFormControl::$__ControlIsSent AbstractFormControl::$controlIsSent
AbstractFormValidator::$__Control AbstractFormValidator::$control
AbstractFormValidator::$__Button AbstractFormValidator::$button
Please note, that the member variables within APFObject and Document are considered as central variables of the APF UI data model. Please ensure, that these variables are renamed during migration within your custom tags.

5. Configuration of log directory

Within release 1.17 the Logger has been redesigned to add more flexibility with configuration of the log file for framework-internal log entries as well as for registration of different LogWriter implementations. Since the new implementation of the Logger includes all functionality of the AdvancedLogger the latter one has been marked as deprecated.

Along with the change of the persistence mechanism of the Logger the configuration of the log directory has changes. In previous versions of the APF the log directory could be configured using a Registry key. Since 1.17 the configuration is applied to the respective LogWriter - the FileLogWriter.

Old definitions of the log directory within the bootstrap file like

PHP code
Registry::register('apf::core', 'LogDir', '/path/to/my/log/dir');

must be changed to

PHP code
/* @var $logger Logger */ $logger = & Singleton::getInstance('Logger'); $target = Registry::retrieve('apf::core', 'InternalLogTarget'); $writer = $logger->getLogWriter($target); /* @var $writer FileLogWriter */ $writer->setLogDir('/path/to/my/log/dir'); $logger->addLogWriter($target, $writer);

Because the framework internally also uses the Logger the standard log target is configurable using the Registry key InternalLogTarget.

6. Configuration of the Logger for framework components

Along with the changes to the Logger described within the previous chapter the configuration of log targets of framework components have changed as well. This primarily applies to the database connection implementations that are using the following targets:

  • sqlite for the SQLiteHandler
  • pdo for the PDOHandler
  • mysqlx for the MySQLxHandler
  • mysqli for the MySQLiHandler

In order to add and configure the necessary log target - depending on the use case - please use the following code block:

PHP code
include('../apps/core/pagecontroller/pagecontroller.php'); import('core::frontcontroller', 'Frontcontroller'); ... // add to your bootstrap file: import('core::logging', 'Logger'); $l = & Singleton::getInstance('Logger'); $dbWriter = clone $l->getLogWriter( Registry::retrieve('apf::core', 'InternalLogTarget') ); $l->addLogWriter('mysqlx', clone $dbWriter); // and/or $l->addLogWriter('mysqli', clone $dbWriter); // and/or $l->addLogWriter('pdo', clone $dbWriter); // and/or $l->addLogWriter('sqlite', clone $dbWriter);

Please note, that the above lines must be added before start of the Frontcontroller.

7. Remove direct access to document attributes within document controllers

Before 1.17 the attributes of the current Document instance have been injected to the respective document controller on transformation of the node to ease the access. This undocumented feature has been removed with this release introducing an interface for document controllers (DocumentController).

Please ensure, that there is no code like

PHP code


PHP code

contained within your document controller classes. In order do access document attributes, please use the following code:

PHP code

8. Switching to alphanumeric proxy ids

As of release 1.17 you can define proxy objects (=references on objects within your custom application) with alphanumeric ids (AppObjectId) within the user management module.

For this reason, the UI and the object definition has been enhanced. In order to use this new feature for your existing epplications, please update the DEFAULT_umgt_objects.ini. The value of the AppObjectId property within the AppProxy object definition now is as follows:

APF configuration
[AppProxy] AppObjectId = "VARCHAR(50)" ...

To apply the changes to the data model, please run the GenericORMapperManagementTool against your database. You can do this using the following script:

PHP code
require('./apps/core/pagecontroller/pagecontroller.php'); import('modules::genericormapper::data::tools', 'GenericORMapperManagementTool'); $update = new GenericORMapperManagementTool(); $update->setContext('{CONTEXT}'); $update->addMappingConfiguration('modules::usermanagement::data', 'umgt'); $update->addRelationConfiguration('modules::usermanagement::data', 'umgt'); $update->setConnectionName('Sandbox-UMGT'); $update->run();

9. Creation and update of GORM-based databases

With release 1.17 GenericORMapperSetup and GenericORMapperUpdate have been combined into one tool. As of this version you are able to create and update databases at the same time with the GenericORMapperManagementTool (see previous chapter). Please note, that GenericORMapperSetup and GenericORMapperUpdate are no longer available.

Switching to the current APF version makes it necessary to adapt all existing setup and update scripts. Examples for the new way can be taken from the current apf-codepack-* release under apps/modules/genericormapper/data/tools/. The two scripts setup.php and update.php both provide a ready-to-use template that must be adapted to your use case only.

Details on the creation and update of databases can be taken from the documentation under Generic o/r mapper.


Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.