widgets.rst 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. Widgets
  2. =======
  3. Widgets are content areas that users can drag around their page to customize the layout. They can typically be customized by their owner to show more/less content and determine who sees the widget. By default Elgg provides plugins for customizing the profile page and dashboard via widgets.
  4. TODO: Screenshot
  5. .. contents:: Contents
  6. :local:
  7. :depth: 2
  8. Structure
  9. ---------
  10. To create a widget, create two views:
  11. * ``widgets/widget/edit``
  12. * ``widgets/widget/content``
  13. ``content.php`` is responsible for all the content that will output within the widget. The ``edit.php`` file contains any extra edit functions you wish to present to the user. You do not need to add access level as this comes as part of the widget framework.
  14. .. note::
  15. Using HTML checkboxes to set widget flags is problematic because if unchecked,
  16. the checkbox input is omitted from form submission.
  17. The effect is that you can only set and not clear flags.
  18. The "input/checkboxes" view will not work properly in a widget's edit panel.
  19. Initialise the widget
  20. ---------------------
  21. Once you have created your edit and view pages, you need to initialize the plugin widget. This is done within the plugins ``init()`` function.
  22. .. code:: php
  23. // Add generic new file widget
  24. add_widget_type('filerepo', elgg_echo("file:widget"), elgg_echo("file:widget:description"));
  25. .. note::
  26. It is possible to add multiple widgets for a plugin. You just initialize as many widget directories as you need.
  27. .. code:: php
  28. // Add generic new file widget
  29. add_widget_type('filerepo', elgg_echo("file:widget"), elgg_echo("file:widget:description"));
  30. // Add a second file widget
  31. add_widget_type('filerepo2', elgg_echo("file:widget2"), elgg_echo("file:widget:description2"));
  32. // Add a third file widget
  33. add_widget_type('filerepo3', elgg_echo("file:widget3"), elgg_echo("file:widget:description3"));
  34. Multiple widgets
  35. ----------------
  36. Make sure you have the corrosponding directories within your plugin
  37. views structure:
  38. .. code::
  39. 'Plugin'
  40. /views
  41. /default
  42. /widgets
  43. /filerepo
  44. /edit.php
  45. /contents.php
  46. /filerepo2
  47. /edit.php
  48. /contents.php
  49. /filerepo3
  50. /edit.php
  51. /contents.php
  52. Elgg 1.8: Default widgets
  53. -------------------------
  54. If your plugin uses the widget canvas, you can register default widget support with Elgg core, which will handle everything else.
  55. To announce default widget support in your plugin, register for the ``get_list, default_widgets`` plugin hook:
  56. .. code:: php
  57. elgg_register_plugin_hook_handler('get_list', 'default_widgets', 'my_plugin_default_widgets');
  58. In the plugin hook handler, push an array into the return value defining your default widget support and when to create default widgets. Arrays require the following keys to be defined:
  59. - name - The name of the widgets page. This is displayed on the tab in the admin interface.
  60. - widget\_context - The context the widgets page is called from. (If not explicitly set, this is your plugin's id.)
  61. - widget\_columns - How many columns the widgets page will use.
  62. - event - The Elgg event to create new widgets for. This is usually ``create``.
  63. - entity\_type - The entity type to create new widgets for.
  64. - entity\_subtype - The entity subtype to create new widgets for. The can be ELGG\_ENTITIES\_ANY\_VALUE to create for all entity types.
  65. When an object triggers an event that matches the event, entity\_type, and entity\_subtype parameters passed, Elgg core will look for default widgets that match the widget\_context and will copy them to that object's owner\_guid and container\_guid. All widget settings will also be copied.
  66. .. code:: php
  67. function my_plugin_default_widgets_hook($hook, $type, $return, $params) {
  68. $return[] = array(
  69. 'name' => elgg_echo('my_plugin'),
  70. 'widget_context' => 'my_plugin',
  71. 'widget_columns' => 3,
  72. 'event' => 'create',
  73. 'entity_type' => 'user',
  74. 'entity_subtype' => ELGG_ENTITIES_ANY_VALUE,
  75. );
  76. return $return;
  77. }
  78. Simple Example
  79. --------------
  80. Here is a simple Flickr widget that uses Flickr's JSON output.
  81. Widget edit page:
  82. .. code:: php
  83. <p>
  84. <?php echo elgg_echo("flickr:id"); ?>
  85. <input type="text" name="params[title]" value="<?php echo htmlentities($vars['entity']->title); ?>" />
  86. </p>
  87. <p><?php echo elgg_echo("flickr:whatisid"); ?></p>
  88. Widget view page:
  89. .. code:: php
  90. <?php
  91. //some required params
  92. $flickr_id = $vars['entity']->title;
  93. // if the flickr id is empty, then do not show any photos
  94. if($flickr_id){
  95. ?>
  96. <!-- this script uses the jquery cycle plugin -->
  97. <script type="text/javascript" src="<?php echo $vars['url']; ?>mod/flickr/views/default/flickr/js/cycle.js"></script>
  98. <!-- the Flickr JSON script -->
  99. <script>
  100. $.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?id=
  101. <?php echo $flickr_id;?>&lang=en-us&format=json&jsoncallback=?", function(data){
  102. $.each(data.items, function(i,item){
  103. $("<img/>").attr("src", item.media.m).appendTo("#images")
  104. .wrap("<a href='" + item.link + "'></a>");
  105. });
  106. $('#images').cycle({
  107. fx: 'fade',
  108. speed: 'slow',
  109. timeout: 0,
  110. next: '#next',
  111. prev: '#prev'
  112. });
  113. });
  114. </script>
  115. <!-- some css for display -->
  116. <style type="text/css">
  117. #images {
  118. height: 180px;
  119. width: 100%;
  120. padding:0;
  121. margin:0 0 10px 0;
  122. overflow: hidden;
  123. }
  124. #images img {
  125. border:none;
  126. }
  127. </style>
  128. <!-- div where the images will display -->
  129. <div id="title"></div>
  130. <div id="images" align="center"></div>
  131. <!-- next and prev nav -->
  132. <div class="flickrNav" align="center">
  133. <a id="prev" href="#">&laquo; Prev</a> <a id="next" href="#">Next &raquo;</a>
  134. </div>
  135. <?php
  136. }else{
  137. //this should go through elgg_echo() - it was taken out for this demo
  138. echo "You have not yet entered your Flickr ID which is required to display your photos.";
  139. }
  140. ?>
  141. How to restrict where widgets can be used
  142. -----------------------------------------
  143. Any plugin that has a widget must register that widget with Elgg. The widget can specify the context that it can be used in (all, just profile, just dashboard, etc.). If you want to change where your users can use a widget, you can make a quick edit to the plugin's source.
  144. Find where the plugin registers the widget
  145. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  146. The function you are looking for is ``add_widget_type()``. It is typically used in an init function in ``start.php``. You should be able to go to ``/mod/<plugin name>/``, open ``start.php`` in a text editor, and find the string ``add_widget_type``.
  147. Changing the function's parameters
  148. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  149. Let's use the friends plugin as an example. We want to restrict it so that it can only be used on a user's profile. Currently, the function call looks like this:
  150. .. warning::
  151. Keep in mind :doc:`dont-modify-core`
  152. .. code:: php
  153. add_widget_type('friends',elgg_echo("friends"),elgg_echo('friends:widget:description'));
  154. To restrict it to the profile, change it to this:
  155. .. code:: php
  156. add_widget_type('friends',elgg_echo("friends"),elgg_echo('friends:widget:description'), "profile");
  157. Notice that the context was not specified originally (there were only 3 parameters and we added a 4th). That means it defaulted to the "all" context. Besides "all" and "profile", the only other context available in default Elgg is "dashboard".