Hi everyone, Q2A 1.7 final is due to be released in the new year! I posted back in November about a few notable changes for plugin/theme developers but there have been a few more since so here are some details. For details on the new file structure, theme 'ranking layout' and plugin init_queries function see the previous thread.
New plugin/theme metadata
We have now settled on a new system for specifying plugin/theme metadata (thanks to pupi1985 for developing this!). Instead of a comment in your PHP/CSS file, each plugin/theme should have an additional file: metadata.json. This uses the JSON format to specify the data which brings more consistency between plugins and themes and language packs, and allows for the potential of more extensibility in future. Here's an example:
{
"name": "Human-readable name of your plugin",
"uri": "Web address for your plugin",
"description": "Human-readable description of your plugin",
"version": "Your plugin version number",
"date": "Build date of your plugin in YYYY-MM-DD",
"author": "Human-readable name of plugin author",
"author_uri": "Web address for plugin author",
"license": "Short name of plugin license, e.g. GPLv2",
"update_uri": "Web address for Q2A to check for updates",
"min_q2a": "Numerical part only, e.g. 1.3",
"min_php": "Numerical part only, e.g. 5.1"
}
For language files, currently there is only one key currently recognised (but others may be used in future).
{
"name": "English (UK)"
}
Note: JSON requires that both keys and values must be in double quotes, and there be no trailing comma after the last item.
If the JSON file is not found Q2A will fall back to the old format, so all add-ons still work in 1.7 without modification. When you add the metadata.json file to your add-on you should keep the old format and update the version number there too, so that users with the old plugin can still see there is an update.
Navigation
There was also a change to how menu items are 'selected'. Previously we checked the array key against the start of the URL to determine if a menu item is selected, but this caused problems on some pages ('user' matched the 'users' and 'user/username' pages as intended, but also custom pages like 'user-activity').
Now when adding custom navigation for your plugin you can specify another element 'selected_on' which lists the URLs that this menu item will be selected on. Example:
$qa_content['navigation']['main']['user'] = array(
'url' => qa_path_html('users'),
'label' => qa_lang_html('main/nav_users'),
'selected_on' => array('users', 'users/', 'user/'),
);
That will set the main "Users" nav to be selected on the appropriate pages. Look at the qa_content_prepare function in qa-page.php for some more examples.
Theme/layer initialization
Several developers have been co-opting the doctype() function in themes/layers for doing extra processing such as fetching options or even running database queries. Firstly, running queries should be avoided in themes where possible - preferably a plugin should be used (maybe a widget or event module).
For other stuff the doctype function is not really suitable. Using __construct is a possibility but slightly more difficult due to calling through to the parent with parameters. So we have added a special initialize() function for this purpose (thanks to pupi1985 for the suggestion), which will be called right after the theme is initialized. When you have done your initialization you must call through to parent::initialize() so that other modules can run their initialization too.
Deprecated functions
As with all software projects, sometimes some functions become outdated or superceded by other methods. Several functions in v1.7 have been marked as "deprecated" so if you are using these in any plugin or custom code you should update your plugins. As per our new deprecation policy in a future version (1.8 or 1.9) using these functions will output deprecated notices, and then removed in a future version.
-
qa-app-admin.php/qa_admin_addon_metadata: use qa_addon_metadata instead.
-
qa-app-posts.php/qa_post_userid_to_handle: use qa_userid_to_handle instead.
-
qa-app-format.php/qa_account_sub_navigation: use qa_user_sub_navigation instead.
-
qa-app-limits.php/qa_limits_remaining: use qa_user_limits_remaining instead.
-
qa-app-options.php/qa_options_set_pending: no longer required.
-
qa-app-posts.php/qa_post_userid_to_handle: use qa_userid_to_handle instead.
-
qa-theme-base.php/qa_html_theme_base: PHP4-style constructor is no longer supported; please use __construct method instead (make sure to call through to parent::__construct as well).
-
qa-theme-base.php/post_avatar: use avatar instead.
-
qa-theme-base.php/ranking_table: table layout is no longer recommended.
-
qa-theme-base.php/ranking_table_item: same as above.
-
qa-theme-base.php/ranking_spacer: same as above.
Also "deprecated" are the marked functions inside built-in plugins like qa-filter-basic.php. They shouldn't be used from other plugins and will be changed to private functions in a future Q2A version.
Now that the codebase has been reorganised hopefully it can be clearer which Q2A functions can be used: in short, any functions from the app, db and util folders are free to be used.
jQuery has also been upgraded to version 1.11, so if your plugin uses jQuery you should check if anything it uses is deprecated. jQuery 1.9 removed some features that were deprecated in 1.7 (most notably, the live() function was replaced by the on() function).
