settings.rst 3.3 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980
  1. Plugin settings
  2. ===============
  3. You need to perform some extra steps if your plugin needs settings to be saved and controlled via the administration panel:
  4. - Create a file in your plugin’s default view folder called ``plugins/your_plugin/settings.php``, where ``your_plugin`` is the name of your plugin’s directory in the ``mod`` hierarchy
  5. - Fill this file with the form elements you want to display together with :doc:`internationalised <i18n>` text labels
  6. - Set the name attribute in your form components to ``param[`varname`]`` where ``varname`` is the name of the variable. These will be saved as private settings attached to a plugin entity. So, if your variable is called ``param[myparameter]`` your plugin (which is also passed to this view as ``$vars['entity']``) will be called ``$vars['entity']->myparameter``
  7. An example ``settings.php`` would look like:
  8. .. code:: php
  9. <p>
  10. <?php echo elgg_echo('myplugin:settings:limit'); ?>
  11. <select name="params[limit]">
  12. <option value="5" <?php if ($vars['entity']->limit == 5) echo " selected=\"yes\" "; ?>>5</option>
  13. <option value="8" <?php if ((!$vars['entity']->limit) || ($vars['entity']->limit == 8)) echo " selected=\"yes\" "; ?>>8</option>
  14. <option value="12" <?php if ($vars['entity']->limit == 12) echo " selected=\"yes\" "; ?>>12</option>
  15. <option value="15" <?php if ($vars['entity']->limit == 15) echo " selected=\"yes\" "; ?>>15</option>
  16. </select>
  17. </p>
  18. .. note::
  19. You don’t need to add a save button or the form, this will be handled by the framework.
  20. .. note::
  21. You cannot use form components that send no value when "off." These include radio inputs and check boxes.
  22. User settings
  23. -------------
  24. Your plugin might need to store per user settings too, and you would like to have your plugin's options to appear in the user's settings page. This is also easy to do and follows the same pattern as setting up the global plugin configuration explained earlier. The only difference is that instead of using a ``settings`` file you will use ``usersettings``. So, the path to the user edit view for your plugin would be ``plugins/your_plugin/usersettings.php``.
  25. .. note::
  26. The title of the usersettings form will default to the plugin name. If you want to change this, add a translation for ``plugin_id:usersettings:title``.
  27. Retrieving settings in your code
  28. --------------------------------
  29. To retrieve settings from your code use:
  30. .. code:: php
  31. $setting = elgg_get_plugin_setting($name, $plugin_id);
  32. or for user settings
  33. .. code:: php
  34. $user_setting = elgg_get_plugin_user_setting($name, $user_guid, $plugin_id);
  35. where:
  36. - ``$name`` Is the value you want to retrieve
  37. - ``$user_guid`` Is the user you want to retrieve these for (defaults to the currently logged in user)
  38. - ``$plugin_name`` Is the name of the plugin (detected if run from within a plugin)
  39. Setting values while in code
  40. ----------------------------
  41. Values may also be set from within your plugin code, to do this use one of the following functions:
  42. .. code:: php
  43. elgg_set_plugin_setting($name, $value, $plugin_id);
  44. or
  45. .. code:: php
  46. elgg_set_plugin_user_setting($name, $value, $user_guid, $plugin_id);
  47. .. warning::
  48. The ``$plugin_id`` needs to be provided when setting plugin (user)settings.