Index: modules/system/system.api-change.php
===================================================================
RCS file: modules/system/system.api-change.php
diff -N modules/system/system.api-change.php
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ modules/system/system.api-change.php	14 Jun 2010 07:05:26 -0000
@@ -0,0 +1,178 @@
+<?php
+// $Id$
+
+/**
+ * @file
+ * API changes between Drupal 6 and Drupal 7.
+ */
+
+/**
+ * @defgroup d6_d7_module_updates Converting 6.x modules to 7.x
+ * @{
+ * This page provides a categorical overview of API changes in Drupal 7.
+ *
+ * @section permissions_and_access_link @ref permissions_and_access
+ * - @ref descriptions_permissions
+ * - @ref permissions_restrict_access
+ * @section form_api_link @ref form_api
+ * - @ref entity_prepare_view
+ * - @ref attached_js
+ *
+ * @section permissions_and_access Permissions and access
+ *
+ * API changes in the permission and access system.
+ *
+ * @subsection descriptions_permissions Permissions have titles (required) and descriptions (optional)
+ *
+ * @link http://drupal.org/node/30984 (issue 1) @endlink
+ * @link http://drupal.org/node/313213 (issue 2) @endlink
+ * @link http://drupal.org/node/601586 (issue 3) @endlink
+ *
+ * In the implementation of hook_permission(), the returned array format
+ * changed.
+ *
+ * Drupal 6 supported this format:
+ *
+ * @code
+ *   function example_perm() {
+ *     return array('administer my module', ...);
+ *   }
+ * @endcode
+ *
+ * Drupal 7 code should use the following format:
+ *
+ * @code
+ *   function example_permission() {
+ *     return array(
+ *       'administer my module' => array(
+ *         'title' => t('Administer my module'),
+ *         'description' => t('Perform maintenance tasks for my module'),
+ *       ),
+ *       ...
+ *     );
+ *   }
+ * @endcode
+ *
+ * Previously, the values were the permission names; now permission names are
+ * the keys and the corresponding value is an array with permission title and
+ * description. If you happen to have composite permission names, which contain
+ * dynamic values such as content type names, look at the array format
+ * generated by node_list_permissions() which is reused by node_permission()
+ * and hook_permission() implementations of other core node modules. Note that
+ * titles are required, but descriptions are optional. You are encouraged only
+ * to use descriptions if you need to tell users something you cannot do using
+ * a title only.
+ *
+ * There is also an additional key ('restrict access') that can be added to the
+ * permission array in rare cases; this is intended for labeling unsafe
+ * permissions and is described in the @ref permissions_restrict_access section
+ * below.
+ *
+ * NB. While no API changes are involved, user.module will now remove
+ * permissions automatically when a module is uninstalled.
+ *
+ * @subsection permissions_restrict_access New 'restrict access' parameter in hook_permission() for labeling unsafe permissions
+ *
+ * @link http://drupal.org/node/248598 (issue) @endlink
+ *
+ * In addition to title and description keys (described in the
+ * @ref descriptions_permissions section above), permissions now have an
+ * optional 'restrict access' key, which can be provided and set to TRUE to
+ * indicate that site administrators should restrict access to this permission
+ * to trusted users.
+ *
+ * This should be used sparingly, for permissions that have inherent security
+ * risks (for example, the "administer filters" and "bypass node access"
+ * permissions provided by Drupal core). When set to TRUE, a standard (but
+ * themeable) warning message will be associated with the permission and
+ * displayed with it on the permission administration page.
+ *
+ * Example:
+ *
+ * @code
+ *   function mymodule_permission() {
+ *     return array(
+ *       'use PHP in mymodule' => array(
+ *         'title' => t('Use PHP in mymodule'),
+ *         'description' => t('Execute arbitrary PHP code on the mymodule administration pages.'),
+ *         'restrict access' => TRUE,
+ *       ),
+ *     );
+ *   }
+ * @endcode
+ *
+ * @section form_api Form API
+ *
+ * API changes in the system for generating and processing forms and form
+ * submissions.
+ *
+ * @subsection entity_prepare_view Added entity_prepare_view() and hook_entity_prepare_view()
+ *
+ * @link http://drupal.org/node/636992 (issue) @endlink
+ *
+ * entity_prepare_view() should now be called during the _build_content() and
+ * _view_multiple() phases of entity rendering. This invokes
+ * hook_entity_prepare_view(), to allow modules to load information which
+ * cannot be done during ENTITY_load() (i.e. other entities).
+ *
+ * @subsection attached_js Attached JavaScript and CSS for forms
+ *
+ * @link http://drupal.org/node/323112 (issue) @endlink
+ *
+ * Individual form elements now have the ability to define what JavaScript and
+ * cascading stylesheets are associated with them. This is stated in the
+ * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/7#attached #attached @endlink
+ * property.
+ *
+ * Drupal 6.x:
+ *
+ * @code
+ *   function example_admin_settings() {
+ *     // Add example.admin.css.
+ *     drupal_add_css(drupal_get_path('module', 'example') .'/example.admin.css');
+ *     // Add some inline JavaScript.
+ *     drupal_add_js('alert("You are visiting the example form.");', 'inline');
+ *     // Add a JavaScript setting.
+ *     drupal_add_js(array('mymodule' => 'example'), 'setting');
+ *     $form['example'] = array(
+ *       '#type' => 'fieldset',
+ *       '#title' => t('Example');
+ *     );
+ *     return $form;
+ *   }
+ * @endcode
+ *
+ * Drupal 7.x:
+ *
+ * Note: for a while, it was suggested to use #attached_css and #attached_js.
+ * Those functions are outdated and no longer work. Please use the examples
+ * below (['#attached']['css'] & ['#attached']['js']).
+ *
+ * @code
+ *   function example_admin_settings() {
+ *     $form['#attached']['css'] = array(
+ *       // Add example.admin/css.
+ *       drupal_get_path('module', 'example') . '/example.admin.css'
+ *     );
+ *     $form['#attached']['js'] = array(
+ *       // Add some inline JavaScript.
+ *       'alert("You are visiting the example form.");' => array('type' => 'inline'),
+ *       // Add a JavaScript setting. Note that when the key is a number, the 'data' property will be used.
+ *       array(
+ *         'data' => array('mymodule' => array(...)),
+ *         'type' => 'setting'
+ *       ),
+ *     );
+ *     $form['example'] = array(
+ *       '#type' => 'fieldset',
+ *       '#title' => t('Example');
+ *     );
+ *     return $form;
+ *   }
+ * @endcode
+ */
+
+/**
+ * @} End of "defgroup d6_d7_module_updates".
+ */
+