Merge pull request #11887 from annando/maxload

[friendica.git] / doc / Addons.md

diff --git a/doc/Addons.md b/doc/Addons.md
index cf4fbdab1251fd5966bbb7a61f2f71654c2a240b..bbc0ed61c19895537eb6ae95df75a7aa6dcd32b8 100644 (file)
--- a/doc/Addons.md
+++ b/doc/Addons.md
@@ -232,14 +232,6 @@ Please note: body contents are bbcode - not HTML
 Called when receiving a post from another source. This may also be used to post local activity or system generated messages.
 `$b` is the item array of information to be stored in the database and the item body is bbcode.
 
-### settings_form
-Called when generating the HTML for the user Settings page.
-`$b` is the HTML string of the settings page before the final `</form>` tag.
-
-### settings_post
-Called when the Settings pages are submitted.
-`$b` is the $_POST array.
-
 ### addon_settings
 Called when generating the HTML for the addon settings page.
 `$data` is an array containing:
@@ -298,6 +290,62 @@ $data = [
 Called when the Addon Settings pages are submitted.
 `$b` is the $_POST array.
 
+### connector_settings
+Called when generating the HTML for a connector addon settings page.
+`$data` is an array containing:
+
+- **connector** (output): Required. The addon folder name.
+- **title** (output): Required. The addon settings panel title.
+- **image** (output): Required. The relative path of the logo image of the platform/protocol this addon is connecting to, max size 48x48px.
+- **enabled** (output): Optional. If set to a falsy value, the connector image will be dimmed.
+- **html** (output): Optional. Raw HTML of the addon form elements. Both the `<form>` tags and the submit buttons are taken care of elsewhere.
+- **submit** (output): Optional. If unset, a default submit button with `name="<addon name>-submit"` will be generated.
+  Can take different value types:
+    - **string**: The label to replace the default one.
+      - **associative array**: A list of submit button, the key is the value of the `name` attribute, the value is the displayed label.
+        The first submit button in this list is considered the main one and themes might emphasize its display.
+
+#### Examples
+
+##### With default submit button
+```php
+$data = [
+       'connector' => 'diaspora',
+       'title'     => DI::l10n()->t('Diaspora Export'),
+       'image'     => 'images/diaspora-logo.png',
+       'enabled'   => $enabled,
+       'html'      => $html,
+];
+```
+
+##### With custom submit button label and no logo dim
+```php
+$data = [
+       'connector' => 'ifttt',
+       'title'     => DI::l10n()->t('IFTTT Mirror'),
+       'image'     => 'addon/ifttt/ifttt.png',
+       'html'      => $html,
+       'submit'    => DI::l10n()->t('Generate new key'),
+];
+```
+
+##### With conditional submit buttons
+```php
+$submit = ['pumpio-submit' => DI::l10n()->t('Save Settings')];
+if ($oauth_token && $oauth_token_secret) {
+       $submit['pumpio-delete'] = DI::l10n()->t('Delete this preset');
+}
+
+$data = [
+       'connector' => 'pumpio',
+       'title'     => DI::l10n()->t('Pump.io Import/Export/Mirror'),
+       'image'     => 'images/pumpio.png',
+       'enabled'   => $enabled,
+       'html'      => $html,
+       'submit'    => $submit,
+];
+```
+
 ### profile_post
 Called when posting a profile page.
 `$b` is the $_POST array.
@@ -570,7 +618,8 @@ Hook data:
 Called when unfollowing a remote contact on a non-native network (like Twitter)
 
 Hook data:
-- **contact** (input): the remote contact (uid = local unfollowing user id) array.
+- **contact** (input): the target public contact (uid = 0) array.
+- **uid** (input): the id of the source local user.
 - **result** (output): wether the unfollowing is successful or not.
 
 ### revoke_follow
@@ -578,7 +627,8 @@ Hook data:
 Called when making a remote contact on a non-native network (like Twitter) unfollow you.
 
 Hook data:
-- **contact** (input): the remote contact (uid = local revoking user id) array.
+- **contact** (input): the target public contact (uid = 0) array.
+- **uid** (input): the id of the source local user.
 - **result** (output): a boolean value indicating wether the operation was successful or not.
 
 ### block
@@ -661,10 +711,6 @@ Here is a complete list of all hook callbacks with file locations (as of 24-Sep-
 
     Hook::callAll('personal_xrd', $arr);
 
-### mod/ping.php
-
-    Hook::callAll('network_ping', $arr);
-
 ### mod/parse_url.php
 
     Hook::callAll("parse_link", $arr);
@@ -696,11 +742,9 @@ Here is a complete list of all hook callbacks with file locations (as of 24-Sep-
     Hook::callAll('addon_settings_post', $_POST);
     Hook::callAll('connector_settings_post', $_POST);
     Hook::callAll('display_settings_post', $_POST);
-    Hook::callAll('settings_post', $_POST);
     Hook::callAll('addon_settings', $settings_addons);
     Hook::callAll('connector_settings', $settings_connectors);
     Hook::callAll('display_settings', $o);
-    Hook::callAll('settings_form', $o);
 
 ### mod/photos.php
 
@@ -722,10 +766,6 @@ Here is a complete list of all hook callbacks with file locations (as of 24-Sep-
     Hook::callAll('home_init', $ret);
     Hook::callAll("home_content", $content);
 
-### mod/poke.php
-
-    Hook::callAll('post_local_end', $arr);
-
 ### mod/contacts.php
 
     Hook::callAll('contact_edit_post', $_POST);
@@ -807,6 +847,10 @@ Here is a complete list of all hook callbacks with file locations (as of 24-Sep-
     Hook::callAll('register_account', $uid);
     Hook::callAll('remove_user', $user);
 
+### src/Module/Notifications/Ping.php
+
+    Hook::callAll('network_ping', $arr);
+
 ### src/Module/PermissionTooltip.php
 
     Hook::callAll('lockview_content', $item);
@@ -919,10 +963,6 @@ Here is a complete list of all hook callbacks with file locations (as of 24-Sep-
 
     self::callSingle(self::getApp(), 'hook_fork', $fork_hook, $hookdata);
 
-### src/Core/L10n/L10n.php
-
-    Hook::callAll('poke_verbs', $arr);
-
 ### src/Core/Worker.php
 
     Hook::callAll("proc_run", $arr);