aboutsummaryrefslogtreecommitdiffstats
path: root/doc/Widgets.md
blob: 7761b1833614c5d59f1868c018953a27af7e9aa4 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
Core Widgets
============

Some/many of these widgets have restrictions which may restrict the type of page where they may appear or may require login


* clock - displays the current time
    * args: military (1 or 0) - use 24 hour time as opposed to AM/PM
<br />&nbsp;<br />

* profile - displays a profile sidebar on pages which load profiles (pages with nickname in the URL)

* tagcloud - display a tagcloud of webpage items

    * args: count - number of items to return (default 24)
<br />&nbsp;<br />

* collections - privacy group selector for the current logged in channel

    * args: mode - one of "conversation", "group", "abook" depending on module
<br />&nbsp;<br />

* suggestions - friend suggestions for the current logged on channel

* follow - presents a text box for following another channel

* notes - private notes area for the current logged in channel if private_notes feature is enabled

* savedsearch - network/matrix search with save - must be logged in and savedsearch feature enabled

* filer - select filed items from network/matrix stream - must be logged in

* archive - date range selector for network and channel pages
    * args: 'wall' - 1 or 0, limit to wall posts or network/matrix posts (default)
<br />&nbsp;<br />

* fullprofile - same as profile currently

* categories - categories filter (channel page)

* tagcloud_wall - tagcloud for channel page only
    * args: 'limit' - number of tags to return (default 50)
<br />&nbsp;<br />

* catcloud_wall - tagcloud for channel page categories
    * args: 'limit' - number of categories to return (default 50)
<br />&nbsp;<br />

* affinity - affinity slider for network page - must be logged in

* settings_menu - sidebar menu for settings page, must be logged in

* mailmenu - sidebar menu for private message page - must be logged in

* design_tools - design tools menu for webpage building pages, must be logged in

* findpeople - tools to find other channels

* photo_albums - list photo albums of the current page owner with a selector menu

* vcard - mini profile sidebar for the person of interest (page owner, whatever)

* dirsafemode - directory selection tool - only on directory pages

* dirsort - directory selection tool - only on directory pages

* dirtags - directory tool - only on directory pages

* menu_preview - preview a menu - only on menu edit pages

* chatroom_list - list of chatrooms for the page owner

* bookmarkedchats - list of bookmarked chatrooms collected on this site for the current observer

* suggestedchats - "interesting" chatrooms chosen for the current observer

* item - displays a single webpage item by mid or page title
    * args:
	* channel_id - channel that owns the content, defualt is the profile_uid 
	* mid - message_id of webpage to display (must be webpage, not a conversation item)
	* title - URL page title of webpage (must provide one of either title or mid)
<br />&nbsp;<br />

* photo - display a single photo
    * args: 
    * url - URL of photo, must be http or https
    * zrl - use zid authenticated link
    * style - CSS style string
<br />&nbsp;<br />

* cover_photo - display the cover photo for the selected channel
    * args:
	* channel_id - channel to use, default is the profile_uid 
    * style - CSS style string (default is dynamically resized to width of region)
<br />&nbsp;<br />


* photo_rand - display a random photo from one of your photo albums. Photo permissions are honoured
    * args: 
    * album - album name (very strongly recommended if you have lots of photos)
    * scale - typically 0 (original size), 1 (1024px), 2, (640px), or 3 (320px)
    * style - CSS style string
	* channel_id - if not your own
<br />&nbsp;<br />

* random_block - display a random block element from your webpage design tools collection. Permissions are honoured.
    * args: 
    * contains - only return blocks which include the contains string in the block name
    * channel_id - if not your own
<br />&nbsp;<br />

* tasklist - provide a task or to-do list for the currently logged-in channel.
	* args:
	* all - display completed tasks if all is non-zero.
<br />&nbsp;<br />

* forums - provide a list of connected public forums with unseen counts for the current logged-in channel.
<br />&nbsp;<br />

* activity - provide a list of authors of unread network content for the current logged-in channel.

* album - provides a widget containing a complete photo album from albums belonging to the page owner; this may be too large to present in a sidebar region as is best implemented as a content region widget. 
	* args:
	* album - album name
	* title - optional title, album name is used if not present
<br />&nbsp;<br />
 

Creating New Widgets
====================

### Class Widgets

To create a class-based widget named 'slugfish' create a file with the following contents:

````
<?php

namespace Zotlabs\Widget;


class Slugfish {

	function widget($args) {

	... widget code goes here.
	... The function returns a string which is the HTML content of the widget.
	... $args is a named array which is passed any [var] variables from the layout editor
	... For instance [widget=slugfish][var=count]3[/var][/widget] will populate $args with
	... [ 'count' => 3 ]

	}

````

The resultant file may be placed in widget/Slugfish/Slugfish.php , or Zotlabs/SiteWidgets/Slugfish.php . It also may be linked from a git repository using util/add_widget_repo.



Traditional function based widget:

If you want a widget named 'slugfish', create widget/widget_slugfish.php containing


    <?php
    
    function widget_slugfish($args) {
    
    .. widget code goes here. See above information for class-based widgets for details.
    
    }


#include doc/macros/main_footer.bb;