Show last authors
1 {{include document="XWiki.DesignClassSheet"/}}
2
3 {{toc start="2"/}}
4
5 == Description ==
6
7 The aim of the gadget integration is to provide XWiki users with a dashboard-like page that will display a list of gadgets. These gadgets can be either internal gadgets (similar to XWiki panels) or external gadgets (coming from the Google Gadget repository for instance). Users can select which gadgets to display on their dashboard from a gadget directory located on the wiki.
8
9 == Basic technical details ==
10
11 * use the existing panel class
12 * add a "URL" field to the panel class to reference external gadgets
13 * personal dashboard of gadgets for each user
14 * create a ?xpage=dashboard view for the User profile
15 * on that view of the user profile, display a gadget dashboard similar to iGoogle
16 * create a list of gadgets / panels from the current wiki
17 * access to the google directory of gadgets
18
19 == Main Elements ==
20
21 === Dashboard Macro ===
22
23 A Dashboard will display XWiki and Google Gadgets grouped in columns, and will support drag&drop inside and between the columns (iGoogle like).
24
25 Dashboards can be added to any document as Dashboard macros. Also, each user will have a Personal Dashboard on their profile page.
26
27 **Personal Dashboard Privacy Settings**
28 We could let each user decide whether her dashboard should be public. However the default setting should be **private**:
29
30 * If the current user has admin rights: shows gadgets of the profileURL user
31 * If the profileURL user has set her dashboard to private & the current user isn't an admin -> don't show the gadgets
32 * If the profileURL user has set her dashboard to public -> show it
33
34 Implementation details. Use:
35
36 * SmartClient library; You can play here with a 3 column dashboard (just a test): http://gsoc.myxwiki.org/xwiki/bin/view/Google+Gadget+and+OpenSocial+Integration/AppDashboard __=> Too heavy__
37 * Scriptaculous based Libraries: [[http://wiki.github.com/madrobby/scriptaculous/draggable]] & [[http://wiki.github.com/madrobby/scriptaculous/droppables]]
38
39 **Dashboard Macro**
40
41 * Parameters: dashboard name, and (maybe) number of columns
42
43 ==== Dashboard Velocity Macro Syntax ====
44
45 ===== **Option 1) One row per gadget, preceeded by the column number** =====
46
47 This is the option currently implemented in the demos linked from the bottom of the page and the code in the sandbox.
48
49 {{code language="none"}}
50 {{dashboard name="<dashboard name>" cols="<number of columns>"}}
51 <column number1> <gadget macro1>
52 <column number2> <gadget macro2>
53 ...
54 {{/dashboard}}
55
56 {{dashboard name="My Dashboard" cols="3"}}
57 1 {{gadget /}} // this gadget is displayed on column 1
58 1 {{gadget /}} // this gadget is displayed on column 1, under the one above
59 3 {{gadget /}}
60 3 {{gadget /}}
61 3 {{gadget /}}
62 {{/dashboard}}
63
64 Result:
65 G1 - G3
66 G2 G4
67 G5
68 {{/code}}
69
70 Drawbacks:
71
72 * defines a meta syntax for the content of the dashboard macro (one line per gadget, column number separated with a space from gadget, etc)
73 * implementation uses parsing of the macro content as string with regular expressions
74 * in this current form, it does not allow layouts more complex than a number of equally sized columns (and extensions of the allowed layouts would require extensions of the meta-syntax, which only make it more complicate)
75
76 ===== **Option 2) One row per column** =====
77
78 {{code}}
79 {{dashboard name="<dashboard name>" cols="<number of columns>"}}
80 <gadget macro1i>... // all gadgets on column 1 (stacked)
81 <gadget macro2i>... // all gadgets on column 2 (stacked)
82 <gadget macro3i>... // all gadgets on column 3 (stacked)
83 {{/dashboard}}
84
85 {{dashboard name="My Dashboard" cols="3"}}
86 {{gadget /}} {{gadget /}} // this gadget is displayed on column 1
87 // no gadgets on column 2, so line empty
88 {{gadget /}} {{gadget /}} {{gadget /}}
89 {{/dashboard}}
90
91 Result:
92 G1 - G3
93 G2 G4
94 G5
95 {{/code}}
96
97 ===== **Option 3) Dashboard stored in an object** =====
98
99 {{code}}
100 Option 3
101 {{dashboard name="Space.Page"/}}
102 {{/code}}
103
104 , where Space.Page contains the XWiki Dashboard object; The object contains the gadgets contained by the dashboard, their order and parameters
105
106 ===== **Option 4) Column macro for layouting, dashboard extends column macro** =====
107
108 Column macro refers to [[extensions:Extension.Column Macro]] (which would be moved to the platform macros). The idea is that, unlike options 1 and 2 above, the dashboard macro does not use a meta-syntax inside, but only regular xwiki 2.0 syntax, and uses the column macro to do the layout. Since the dashboard macro should not be about much more than layout, the dashboard macro would only extend the sections macro (the one specifying that a columns section starts). This differentiation between dashboard and regular section macro is important because: 1/ it would ignore all content which is not an instance of a gadget macro (only a macro from the "gadgets" category can be used as a macro, any other wiki syntax is ignored) 2/ it will have custom behaviour on editing (inline editing) ~-~- drag and drop, editing macros/gadgets parameters, etc, 3/ in general it's good to know whether something is a dashboard or only columns layout (it's semantic).
109
110 Implementation of the dashboard macro would be based on manipulating XDOM instead of parsing meta-syntax with regular expressions (as the current implementation for 1 does).
111
112 Since section / column macros can be nested, it's very easy to create complex layouts (with split columns, etc), and also, all layouting contributions added for the purpose of dashboard (e.g. percent width columns) would be improvements to the columns layouting in general.
113
114 With this implementation, sizes of the gadgets would be controlled by the dashboard's column layout, the gadgets are not responsible for declaring and setting their sizes (same is on iGoogle, gadgets are all scaled to fit the width of the column, whichever that is). However, if a gadget would want to have a specific size, it could have it (in the end a gadget can generate whatever html it wants). This allows good usage of existing xwiki macros as gadgets, since they don't need more parameters or extra code to work in a dashboard. For the gadget title, we could decide that the dahsboard macro would read the title from a gadget parameter but this can create problems with existing parameters of that macro, or we could decide that a gadget is responsible for exposing its own title. As well, the dashboard macro could add extra html around its gadgets in view mode (for decoration purposes) or could just render them as they are.
115
116 {{code}}
117 {{dashboard name="my dashboard" style="gnome"}}
118 {{column}}
119 {{gadget /}} {{gadget /}}
120 {{gadget /}}
121 {{/column}}
122
123 {{column}}
124 {{gadget /}} {{gadget /}}
125 {{section}}
126 {{column}} ... {{/column}}
127
128 {{column}} ... {{/column}}
129 {{/section}}
130 {{/column}}
131 {{/dashboard}}
132 {{/code}}
133
134
135 ====== Implementation ======
136
137 **In view mode**, the dashboard macro will only display the content inside, parsed as wiki syntax, just like the section macro does (no special containers for the gagdets, no extra divs or anything). There is a choice to make about filtering the syntax which does not represent macro calls:
138
139 1. filter all wiki syntax which is not a (gadget) macro call, assuming that only macros in a specific category could be used as gadgets. This approach comes from the fact that the dashboard editor will not be able to edit these random wiki syntax sections, and limiting its content will make the 2 ways of editing the dashboard consistent: what can be created from editing wiki sytnax can also be created from the editor.
140 1. don't filter syntax. Allow power users to create more complex dashboards from the wiki editor, even if from the dashboard editor only gadget macros can be manipulated. Build the dashboard such that it can still edit as much as possible the gadgets, even in this case. The con for this approach is that users might find this confusing, they might not be able to reproduce some dashboards that they see and don't understand why, and also the dashboard editor could be slightly more error prone, and inconsistency prone.
141
142 **In edit mode**, the idea is that editing would be done in the inline edit mode for the document containing the dashboard. The dashboard should be rendered **just like in view mode** only that with **annotated html syntax**, by passing the outputSyntax parameter to the inline edit URL, with a jsx loaded by the dashboard macro only in inline mode. The dashboard javascript will identify the gadgets in the dashboard by the annotated html comments and allow users to manipulate these gadgets. These changes will be saved in the document by using a hidden input for the document content in wiki syntax, which will be updated to the new value by the dashboard javascript, with an ajax call to a **server service** (REST resource). Since modifying the annotated html resulted from a macro rendering does not automatically parse back to wiki syntax using the html parser, but the content of the macros needs to be updated (think about the case of a gadget being moved from a column to another, the content of the toplevel dashboard macro needs to be updated), there are 2 approaches we could take:
143
144 1. when something is changed on the client (move a gadget from a column to another, add a gadget, delete a gadget) the js on the client will have the new HTML corresponding to the new content but with outdated annotations. It will send this content to the service, along with a method to identify the dashboard which is being edited in the page (id, for example). The server will parse the DOM of this HTML to obtain the new dashboard macro content by going to the leaf level macros (all macros that don't contain section / column macros anymore) and parse these back to wiki syntax, and so on going up on the parent generating the wiki syntax content of the nested column macros, section macros and finally the toplevel dashboard macro. Note that such a parser doesn't exist yet, it needs to be implemented for this purpose. The updated dashboard macro block such obtained will replace the edited dashboard node in the XDOM of the document (identified by the id), and the serialization as wiki syntax will be the new content of the document, sent as a response to the client to be set in the appropriate content hidden input to be saved.
145 1*. pros: inline with the idea of the wyiswyg editor, which is based on parsing the annotated XHTML back into wiki syntax; only one point of custom model, namely parsing the edited XHTML with outdated annotations, which can be isolated in a single class.
146 1*. cons: quite complicated to understand the flow, how the changes on the client endup being reflected in the wiki content of the page; custom parser for the modified HTML to be parsed in the updated dashboard macro call can be non-trivial;
147 1. given that there is a 1-1 correspondence between the tree of gadgets / layout elements inside the dashboard and the corresponding XDOM nodes, an operation based editing can be used: everytime something changes on the client (add gadget, move gadget from a column to another, etc) the operation is sent to the server along with its parameters (name, parameters and position of the added gadget or the initial position and final position of the moved gadget, etc), where it is operated on the XDOM of the document and the serialization as wiki syntax of this xdom is sent as the result to the client, to be set in the appropriate content hidden input to be saved.
148 1*. pros: clear, easy to understand approach, good mapping between the operations that the client js will use anyway (add, edit params, delete, move, etc) to server side operations on the content;
149 1*. cons: different model, needs a bit of scaffolding to define the model for operations, etc; quite limiting (in terms of allowing extra actions in the future on the dashboard), it really depends on the ability to split user actions on the dashboard in serializable operations in a way which makes them reproducible on the server side; applying operations on the server side XDOM is not straightforward either, because the whole tree does not exist at any point (it's just a single Dashboard macro node, with its wiki 2.0 content holding the column macro calls and the gadget macro calls)
150
151 Note that the transformation of changes in XHTML to changes in wiki can be done either on each operation, to be kept in sync all the time, or all at the end. Various user interaction tricks can be used to make all this transparent to the user.
152
153 ===== **Option 5) Gadget entries stored in objects, dashboard macro only pinpoints the position in the page** =====
154
155 The whole point of this approach is to make it easy to edit the dashboard by storing gadgets in structured content, rather than unstructured, wiki syntax.
156
157 Gadgets could be stored in objects in the page, and the dashboard macro (~{~{dashboard /}}) will read all these objects and draw the dashboard. The objects, DashboardEntry, will contain the following fields:
158
159 * title, which could be velocity code to allow translations
160 * content, which will be wiki syntax. In the case of a gadget added from a macro, it will be a macro call. A + for this case is that this allows to easily adding "one time gadgets" without necessarily creating a macro for it
161 * position, free field which will make sense depending on the layout chosen for the dashboard. As we thought of it now, it should be a pair of numbers, (container, index), which will allow a gadget to identify the container in which to be placed (e.g. a column index in case of a columns dashboard or more general, an identifier), and its index inside that container. Generally, all layouts should have the notion of gadget container, an element (XDOM or HTML) where gadgets can be placed inside that layout, to differentiate, for XDOM or HTML, these elements from other layout elements.
162 * potentially we could add a dashboard name, to allow gadgets for multiple dashboard in the same document.
163
164 The dashboard macro will work as following:
165
166 * it will take, as today, a layoutStyle parameter, which will point to predefined layouts. By default, the style will be columns. The number of columns to layout will be taken from the number of columns specified in the dashboard entry objects in the position field
167 * when layoutStyle is missing, a layoutType parameter will specify a syntax for the layout of the dashboard (e.g. xul or html) and the content of the dashboard will be a piece of containers definition in this syntax, with ids to identify them. The only restriction for the layout specification is to be convertible in XDOM, since the dashboard macro needs it in XDOM for rendering the gadgets inside ~-~- This will not be implemented right away as the 80% case, the columns layout is addressed by a predefined layout.
168 * All this information can be stored in an object, to allow editing the dashboard layout without changing the content of the document (which as we've seen above in option 4), is not easy).
169 * A "source" parameter can be added to the dashboard, to specify the document to read the dashboard entry objects from.
170
171 Besides making the editing easier, as the editing code will manipulate real structured data instead of having to make sense of the wiki syntax, this approach also allows to have a dashboard macro in a velocity script, thus making it easier for rights checking, or personal dashboards implementation, or dashboards added with the ~{~{include}} macro.
172
173 Also, because data is more structured than in option 4), it will be easier for a velocity script, for example, to manipulate a dashboard programatically (XDOM can be a bit incomfortable to manipulate in velocity).
174
175 === Wysiwyg editing of the dashboard ===
176
177 ==== Option 1) NO WYSIWYG preview, adding Gadgets through Gadgets/Macros Directory or macro content field ====
178
179 * WYSIWYG Insertion: no Preview [[[Mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal1#HInsertDashboardMacroWYSIWYGDialog]]]
180 * result after insertion (view mode): empty dashboard with appropriate message and a 'Add more gadgets' button at the top which goes to Gadgets/Macros Directory [[[Mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal1#HResultafterInsertDashboardMacroWYSIWYGDialog]]]
181 * adding Gadgets to the Dashboard (2 alternative ways):
182 ** by editing the Dashboard macro and writing wiki syntax (for the gadget macros) in the content text area
183 ** through the Gadgets/Macros Directory; user clicks 'Add more gadgets' on dashboard which sends user to Gadgets/Macros Directory, from where gadgets are added by clicking 'Add it now' buttons next to gadgets/macros
184
185 ==== Option 2) WYSIWYG preview, adding Gadgets through WYSIWYG Macro Insertion dialog ====
186
187 * WYSIWYG Insertion: with Preview (Add/Edit/Delete/Drag&Drop gadgets on the dashboard from here) [[[Mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal2#HInsertDashboardMacroWYSIWYGDialog]]]
188 * result after insertion (view mode): dashboard with gadgets and a 'Add more gadgets' button at the top which goes to Gadgets/Macros Directory
189 * adding Gadgets to the Dashboard (2 alternative ways):
190 ** through WYSIWYG Macro Insertion dialog
191 ** through the Gadgets/Macros Directory; user clicks 'Add more gadgets' on dashboard which sends user to Gadgets/Macros Directory, from where gadgets are added by clicking 'Add it now' buttons next to gadgets/macros
192
193 === Gadgets Directory ===
194
195 **Local Directory**
196 There will be an internal gadget directory in the wiki. This directory will be divided in 3 parts:
197
198 * XWiki Gadgets defined in the wiki / in the farm (current Panels)
199 * Google Gadgets selected out of the global Google Directory by wiki admins
200 * If allowed by wiki admins: full Google Gadgets Directory
201
202 The Local Directory should contain have a list relevant Gadgets for the wiki; safe / approved / checked if works by admins; relatively small list (compared to Google Gadget Directory).
203
204 **Adding Gadgets to the Dashboard**
205 Users can add gadgets from the local repository. If the local repository lets the access to all Google gadgets open, any Google gadget can be added (after being added to the Local Directory in the background)
206
207 **Adding Gadgets to the Directory**
208 Who can add gadgets to the wiki directory: Admins or Users or configurable? Configurable:
209
210 * Only admins
211 * Users with admin validation
212 * Users without validation
213
214 === Gadget Macro/s: One or Multiple Gadget Macros? ===
215
216 ==== Option 1) A single Gadget Macro ====
217
218 A gadget macro would look like:
219 ~{~{gadget type="Gadgets.GoogleDocs" width="100" title="some title" GD_userpref1="val1" GD_userpref2="val2" ... /}}
220 or
221 ~{~{gadget type="Gadgets.GoogleDocs" width="100" title="some title" userprefs="GD_userpref1=val1&GD_userpref2=val2&..." /}}
222
223 , where Gadgets.GoogleDocs, is the document which describes the specific Gadget; can also be a Panels.PanelName for XWiki Gadgets
224
225 ==== Option 2) Multiple gadget macros, one for each Gadget ====
226
227 The gadget macros would look like:
228 ~{~{googledocs height="100" width="100" title="some title" GDocs_userpref1="val1" GDocs_userpref2="val2" ... /}}
229 ~{~{worldclocks height="100" width="100" title="some title" WC_userpref1="val1" WC_userpref2="val2" ... /}}
230
231 , where GD_userprefi are the User Preferences specific to Google Docs gadget, and WC_userprefi are the User Preferences specific to WorldClocks Gadget. The User Preferences are defined within a gadget's XML by the Gadget's creators.
232
233 **Consequnces Option 2)**
234
235 * Two different actions: (1) "import" gadgets (mostly for admins/but also users - configurable) (2) add gadgets (already transformed into macros) to the Dashboard (any user)
236 * Need for a Macro Directory (instead of a Gadget Directory) (Manage Macros from here: edit/import/delete)
237 * Would **Add Macro to my Dashboars/Any Dashboard/Panel** action in the Macros Directory still make sense? (Similar to "Add Macro to my Dashboars/Any Dashboard/Panel" action in the Gadgets Directory)
238
239 **Pro Option 2)**
240
241 * Use the same WYSIWYG insert macro dialog for Gadgets too
242
243 **Cons/Questions Option 2)**
244
245 * Macro name conflict with regular macros; but solved with the "gadget:" namespace prefix (see Option 3)
246 * Wiki macro authors need to have programming rights (to "import" gadgets from Google Directory as XWiki macro) & macros can be defined only in the main wiki of a XEM => In the future, any user should be able to "import" a gadget, provided he has write access to the space where the gadget is imported; Some Macros might not be visible to some other users. This could be solved by allowing users to "import" gadgets in only one space (e.g. Macros space)
247
248 ==== Option 3) Multiple gadget macros with namespace prefix ====
249
250 To distinguish easily between the other macros and Gadgets (and have different namespaces), we could prefix the Gadgets with the 'gadget' prefix, like:
251 ~{~{gadget:googledocs ...}} and ~{~{gadget:worldclocks ...}}, as Marius Florea suggested.
252
253 === Panel Wizard ===
254
255 * Keep the same location for the Panel Wizard: http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=Panels.PanelWizard&forceLeftPanels=1&forceRightPanels=1&section=Panels.PanelWizard
256
257 **Gadgets Directory vs. Panel Wizard (differences/why distinct?)**
258 //**Gadgets Directory:**//
259
260 * must be accessible to all users
261 * Role: allows all users to browse all Gadgets and add them to a dashboard macro, personal dashboard or even a side panel container (only admins)
262
263 //**Panel Wizard:**//
264
265 * must be accessible only to Admins
266 * Role: customize the side menus, how many panels to display and in which order; specify the content of these panels (which Gadgets to display by picking them up from the Gadgets Directory)
267
268 ==== Option 1) Panels become only empty containers with no content (empty shells) ====
269
270 The Panel Wizard would only let you specify how many panel-container to put and where to put them and once you've defined where panels will be, you populate them using the XWiki/Google Gadget Directory. The Admin will drag&drip the shell panels into the side panels and rearrange them also by drag&drop. [[image:http://incubator.myxwiki.org/xwiki/bin/download/Mockups/GadgetsIntegration/gadgetsIntegrationProposal1PanelWizard.png||height="100" width="120"]]
271 [[See mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegration#HPanelWizard]]
272
273 ==== Option 2) Gadgets also displayed in the Panel Wizard, in addition to the Gadgets Directory ====
274
275 The Admins will have direct access in the Panel Wizard to the XWiki/Google Gadget Directory by displaying the Gadgets in the Panel Wizard. The Gadgets won't be completely rendered, but have displayed just the tile, thumbnail and a small description and paged in such way that user won't need to scroll down. The will drag&drop the gadgets into the side panels.
276
277 **Cons Option 2)**
278
279 * The functionality of browsing gadgets will be duplicated in 2 places
280
281 ==== Option 3) Have a mini representation of the layout ====
282
283 The mini representation of the layout will have side columns with small boxes in place of the gadgets, that can be rearranged inside and between the columns. Each gadget will only display the title of the gadget, and edit and delete button. In each of the side columns, an **Add Gadget** link will be displayed. Both the Add gadget and the edit will open the WYSIWYG insert macro dialog box, respectively modify macro dialog box.
284 [[See mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal2#HPanelsWizard]]
285
286 == XWiki as Open Social Container ==
287
288 In the following section, when discussing about Open Social gadgets, we will refer to the specification at [[http:~~/~~/opensocial-resources.googlecode.com/svn/spec/1.0/OpenSocial-Specification.xml>>http://opensocial-resources.googlecode.com/svn/spec/1.0/OpenSocial-Specification.xml]] and the target is to build a **Core Gadget Container** as per the compliance specification in that reference. It means that XWiki will be a gadget container but will not provide the social api for these gadgets to use (at least for the moment). A few terms will be used in this section and, to make sure they mean the same thing for everybody, here's the list:
289
290 * //XWiki Gadgets System// ~-~- a system of gadgets to be used to build dashboards with gadgets for xwiki (which is the target of this proposal), regardless of whether these gadgets are according to the open social spec or not (implementation could be any).
291 * //Open Social Gadget// ~-~- a gadget published somewhere in the www, using the open social specification for gadgets definition.
292 * //XWiki Gadget// ~-~- a gadget to be used on such a dashboard in XWiki which contains information from the wiki, regardless of the implementation (it's not necessarily an open social gadget, but it could be).
293
294 === Using external open social gadgets in an XWiki Dashboard ===
295
296 This section is to discuss how will the external open social gadgets (google gadgets or other) be used inside the XWiki gadgets system. There are 2 issues to discuss, the usage paradigm and the actual technical solution. First the usage:
297
298 ==== Option 1) Import before use, potentially by admin ====
299
300 this means that before they can be used in a dashboard, a gadget must be imported and approved by an admin, who would specify the gadget definition XML, to be handled (and potentially transformed in some sort of XWiki representation of gadgets) by the gadgets component.
301
302 **Pros:** there is control of what code gets to be executed in XWiki, there can be a coherent gadgets directory built (based on the gadgets already imported), it allows specialized handling of the gadgets when added to the dashboard or to a page, in terms of form used for the user preferences
303
304 **Cons:** less freedom for users / developers to use whatever they want as gadgets, there's an extra step to be done, potential bloat of the wiki by importing one-time-use gadgets
305
306 ==== Option 2) Use by (any) definition URL, and list of parameters ====
307
308 this means that when a user will want to add a gadget to a dashboard, they would only specify the url to the XML specification of the gadget, along with the user preferences to be used for the gadgets instance. Control could also be added in terms of domain from which gadgets are approved.
309
310 **Pros:** more freedom for the developers (as any gadget could be used just by a link to its definition URL), less bloat
311
312 **Cons:** less control of what code gets executed in the wiki, no control of the versions of the gadget used (the XML definition would automatically be read when used)
313
314 Note that even if option 1) is implemented, the pros of option 2) can be achieved by allowing import to everybody, or creating a 'generic gadget' gadget, which would read an XML spec and render the gadget in it.
315
316 The second discussion is about the technologies used to implement the open social core gadget container in xwiki. One approach is the partial integration of Apache Shindig as it was started during the GSoC by AnaMaria.
317
318 In the existing implementation, the imported google gadgets are rendered using the google container, by creating the HTML used by google to allow embedding of these gadgets in web pages (however I didn't find the documentation for that). Should we keep this approach?
319
320 === Publishing XWiki Gadgets as open social gadgets ===
321
322 Gadgets used on the xwiki dashboard, if not coming from imported open social gadgets, should also be published as open social gadgets, as well as any other wiki content that might be interesting as a gadget to be used in other open social containers. According to the opensocial standard, the only thing needed to be done to publish a gadget is to make available its XML specification, which contains preferences definition and gadget content (either as an URL to be requested everytime the gadget it rendered or directly as html + javascript to be rendered by the container).
323
324 One of the choices to be made is about the human assistance in defining these gadgets. It can be:
325
326 ==== Option 1) Automatic generation of the gadgets specification ====
327
328 potentially from a Gadget XWiki object, which will define the parameters of the gadget and the content of the gadget (either wiki code to be executed for a gadget with content to be fetched from url) or html and javascript for html gadgets. This gadget object could be generated, for the gadgets defined as xwiki macros (see ~[~[Option 2 >> GadgetIntegration#HOption229Multiplegadgetmacros2ConeforeachGadget]] above), automatically from the macros specification: params and content would become user preferences, etc. Also the gadget object could be automatically generated for a wiki document which could be published as a gadget with the click of a button. The generation of the XML or of the gadget content (when requested by the container) could also be done through an action, or a template.
329
330 ==== Option 2) Manual specification of the gadgets ====
331
332 basically it means that we either leave it to the developers to handle XML definition, or use a single Gadget XWiki Object to specify the XML with better UIs, but do little to no assistance in automatically transforming a page / macro into a gadget.
333
334 This is more an option of whether we think it's very important to automatically generate it and easen the developer's job or not generate it.
335
336 Another aspect to decide is whether it's important to allow users/ developers to "write gadgets" in wiki syntax in a wiki style gadgets spec, or only allow html & js specification of the gadgets.
337
338 ==== Option A) favor gadgets in wiki syntax ====
339
340 and implement all mechanisms for the wiki syntax to be published as a gadget (see Option 1) above). These mechanisms might include automatic generation of html from the wiki syntax, but, since user preferences / parameters must be taken into account, it might not be straightforward.
341
342 ==== Option B) gadgets are HTML & JS or hrefs ====
343
344 and basically leave it to the user if they want to transform a piece of wiki syntax / page in a gadget, to handle the transformation of the content generated from wiki syntax into gadget content. This would favor developers that have experience with gadgets and know the paradigm, and expect gadgets to be written in HTML & JS, as per the specs.
345
346 == Full Proposals ==
347
348 The important aspects to discuss when it comes to full proposals of supporting (open social) gadgets in xwiki are:
349
350 1. how will a gadget be represented in the xwiki gadgets system (from a technical point of view)
351 1. implementation of XWiki as an Open Social Container (see above) ~-~- use external gadgets and publish data as gadgets
352 1. what is a Dashboard (from a technical pov) and how does it contain its gadgets\\
353
354 After making the above issues clear, additional concerns such as the gadgets directory, the interaction with the gadgets dashboard, etc, can be built on top. Based on the individual options for the aspects above, there are 2 proposals:
355
356 === Proposal A - Gadgets are XWiki macros ===
357
358 The dashboard is a macro and it contains macros inside so that gadgets are xwiki macros, any xwiki macro can be used as a gadget.
359
360 * open social gadgets are imported in the wiki ([[option 1)>>#HOption129Importbeforeuse2Cpotentiallybyadmin]] above) as macros, each gadget in an individual macro ([[option 2)>>#HOption229Multiplegadgetmacros2ConeforeachGadget]] above)
361 * existing xwiki macros can be used alongside gadget macros in the dashboard
362 * automatic export of xwiki macros to open social macros should be implemented to allow publishing XWiki gadgets as open social gadgets ([[option 1)>>#HOption129Automaticgenerationofthegadgetsspecification]] above )
363
364 The idea is that, in the xwiki gadgets system, the gadgets are macros and all macros can be used as gadgets, and mechanisms will be provided to import from and export to the open social format.
365
366 Gadgets, because they are macros, will be usable in any xwiki document.
367
368 **Pros:**
369
370 * each gadget has its own type (the macro to which it's imported) which is well defined: we know all params and the types of these params, when gadgets would be used as macros inside a page (not necessarrily in a dashboard) and added through the wysiwyg, we'll have specialized forms (know all params and their types, etc).
371 * XWiki macros can be immediately used in a dashboard, without extra effort.
372 * closer to an xwiki model for the gadgets (easier to build xwiki gadgets and dashboards for users which are already used to xwiki)
373
374 **Cons:**
375
376 * representation of gadgets as xwiki macros (one for each gadget) constitutes an extra model layer for the XWiki Gadgets system.
377
378 === Proposal B - All gadgets are open social gadgets ===
379
380 The dashboard is a macro and it contains calls only to the ~{~{gadget}} macro inside.
381
382 * there is a special macro called ~{~{gadget}} to be used for this purpose ([[option 1)>>#HOption129AsingleGadgetMacro]] above)
383 * the ~{~{gadget}} macro will use the gadget XML URL as a parameter ([[option 2)>>#HOption229Useby28any29definitionURL2Candlistofparameters]] above) for the open social gadgets
384 * the same ~{~{gadget}} macro will be used for the XWiki Gadgets, only that instead of the URL will take an xwiki page name as a parameter
385 * for the XWiki Gadgets, some sort of automatic generation of the gadget specification from a page could be provided to unify the 2 types of parameter for the ~{~{gadget}} macro ([[option 1)>>#HOption129Automaticgenerationofthegadgetsspecification]] above)
386
387 The idea is that the dashboard only operates with one type of content, open social gadgets. These gadgets can be either external gadgets, or xwiki content / gagdets, automatically transformed into open social gadgets. The advantage of this idea is the simplified approach, and the implementation of the open social container in the open social spirit rather than in the xwiki spirit, conversion and work being in the direction of exposing xwiki content as open social content (which is a pro).
388
389 Gadgets, because they are macros, will be usable in any xwiki document, just as for the proposal above.
390
391 **Pros:**
392
393 * simpler approach,
394 * no extra layer, the ~{~{dashboard}} only operates with open social gadgets (implementation in the spirit of the open social container), easier to use for developers already used to the open social gadgets model
395
396 **Cons:**
397
398 * potentially extra work to make sure that all xwiki content can be automatically represented as a gadget, to be used in the dashboard.
399 * generic gadgets, no possibility of providing specific forms for inserting gadgets in pages (for example, the macro wizard in the wysiwyg won't be able to provide a form with the needed parameters).
400
401 ----
402
403 Additional proposals (old work):
404
405 === Proposal 1 - Gadgets added on Dashboards through Gadgets Directory, and not WYSIWYG Insert Macro Dialog ===
406
407 The Dashboard macro is just a container and when you add it in a document, it simply prints a small "add more gadget(s)" link . This link sends the user to the Gadgets Directory, together with a URL parameter which specifies the dashboard to add the gadgets to. However, inside the directory, when a gadget is added by clicking 'add it now' button under a gadget, the gadget is not directly added to the dashboard referenced in the URL, but a dialog window pops up which asks the user explicitly this. Options for adding it to the person dashboard or another dashboard are provided.
408
409 Looking at things this way, the Panel Wizard would only let you specify how many panel-containers to put and where to put them. Once you've defined where panels will be, you populate them using the XWiki gadget repository. The Panels would be like empty shells which can still be drag&dropped to reposition.
410
411 See [[Mockups for GadgetsIntegration - Proposal 1>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal1]]
412
413 === Proposal 2 - Multiple Macros - each XWiki&Google Gadget as its own Macro ===
414
415 Each XWiki and Google Gadget would be a distinct Macro (Option 2 for [Gadget Macro(s): One or Multiple Gadget Macros? >http://dev.xwiki.org/xwiki/bin/view/Design/GadgetIntegration#HGadgetMacro28s293AOneorMultipleGadgetMacros3F])
416
417 This way gadgets will be inserted by using the WYSIWYG Insert Macro dialog, and the user would directly choose the gadget-macro she prefers. The 2nd window would ideally be extended to contain a Preview area (see [[mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal2#HInsertGadgetMacroWYSIWYGDialog]]).
418
419 The Dashboard would also be a macro. The 2nd window in the WYSIWYG Insert Macro dialog would ask for the dashboard name and number of columns, and a preview will be provided. In the Preview area, you will be able to click a 'Add Gadgets' button, edit, delete and rearrange the gadgets (the gadgets in the preview area will not be rendered - they will be just small colored boxes). When 'Add Gadgets' is clicked, a new window will appear to choose a macro, continued with the preview and settings for that macro. (see [[mockup>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal2#HInsertDashboardMacroWYSIWYGDialog]])
420
421 As for the Panel Wizard, we would have a mini representation of the layout. See Option 3) Have a mini representation of the layout in [[Main Elements - Panel Wizard>>http://dev.xwiki.org/xwiki/bin/view/Design/GadgetIntegration#HPanelWizard]]
422
423 See [[Mockups for GadgetsIntegration - Proposal 2>>http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal2]]
424
425 == Scenarios ==
426
427 * [[Gadget Scenarios Prioritized]]
428
429 Following are a few usage scenarios for the gadgets feature, where, in the brackets, we have marked which of the proposals above favor them (meaning that it would be easier to implement / more straightforward in that case), if there is unbalance between the 2 proposals. Also, under the scenarios I have listed possible paths for each scenario.
430
431 1. User adds a dashboard to a page, next to other content (between text parts, for example).
432 1. User navigates a list of available gadgets (from xwiki or open social gadgets) and adds one to a dashboard. (slightly favored by option A)
433 1. User rearranges the gadgets on the dashboard by dragging and dropping them to their new places.
434 11. directly, view mode is also edit mode
435 11. pushes a button to switch the dashboard to edit mode, does the changes, and pushes a button to save the changes
436 1. User edits the parameters of a gadget by pushing a button displayed next to the gadget in the dashboard.
437 1. User removes a gadget from a dashboard by pushing a button displayed next to the gadget in the dashboard.
438 1. User edits the gadgets in the dashboard and their organization using wiki syntax, and not the visual editor (favored by option A, it would be very hard to know the right parameters to use for option B).
439 1. User creates a dashboard layout in asymetric manner (not all gadgets have the same size, unbalanced columns, etc ~-~- for example think of the current Main.WebHome, where recent changes, spaces, tagcould would be gadgets).
440 1. User adds a new open social gadget to a dashboard (one which does not exist in the gadgets directory yet).
441 11. by just specifying the gadget URL (favored by option B)
442 11. user has to import the gadget before he can use it (favored by option A)
443 1. User adds a gadget in a wiki page without necessarily having a dashboard in that page, just next to content, for example (favored by A, for which a better interaction for this task will be provided).
444 1. User easily creates a gadget whose content is a fragment of wiki syntax. (favored by option A where users can already use an existing macro to achieve this purpose)
445 1. Developers can expose an XWiki Gadget as an open social gadget with the click of a button.
446 1. Users want to operate with the dashboard as with a collection of gadgets: all operations are on gadgets (add gadget, remove gadget, edit gadget) not other elements (like text or links, etc).
447 1. When the user accesses a dashboard, it should render fast and easy (as opposed to the jira 4 dashboard, for example). (potentially favored by option A), depending on some technical details )
448
449 == Q&A ==
450
451 1. **How should Gadgets in Directory be stored?**
452 11. - Use the same Panels.PanelClass for Gadgets? Append fields? (URL, other?)
453 1. **How should Installed Gadgets be stored? (Installed Gadget by User)**
454 11. - Create an InstalledAppClass with reference to user ID (user doc's fullName) and app ID (gadget doc's fullName)
455 1. **Where should Gadget UserPrefs be stored?**
456 11. - UserPrefs are made or key/value pairs
457 11. - Bind UserPref both to Gadget/Panel ID and User ID (installed Gadget by user); (store user ID / gadget ID / key / value for each pref)
458
459 == Google Gadgets fields / XWiki Panels fields ==
460
461 Required fields when submitting a Gadget to Google Directory: [[http://www.google.com/ig/submit]] ([[http://code.google.com/apis/gadgets/docs/publish.html#Submitting]])
462
463 * title
464 * description
465 * author
466 * author_email
467 * screenshot (suggested)
468 * author_location (suggested)
469 * author_affiliation (suggested)
470 * title_url (suggested)
471 * directory_title (required if title contains user prefs)
472
473 XWiki Panels.PanelClass fields:
474
475 * name
476 * type
477 * description
478 * content ==> for Gadgets not used
479 * category
480
481 (% style="list-style-type: square;" %)
482 * User should only submit URL of gadget when adding it directly to the wiki directory (like form Submit your gadget on [[http://www.google.com/ig/submit]]) ---> and not added from iGoogle directory--
483 * We should parse the XML and check for required fields + keep (some of) them in the Gadget XWiki Class/Panel
484
485 == Related ==
486
487 === Mockups ===
488
489 * [[http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegration]]
490 * [[http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal1]]
491 * [[http://incubator.myxwiki.org/xwiki/bin/view/Mockups/GadgetsIntegrationProposal2]]
492
493 === Demo on Incubator ===
494
495 * [[http://incubator.myxwiki.org/xwiki/bin/view/Macros/Demo]]
496
497 === UI Design by [[evalica>>http://www.xwiki.org/xwiki/bin/view/XWiki/evalica]] ===
498
499 * Gadgets Directory: [[http://incubator.myxwiki.org/xwiki/bin/view/Improvements/GadgetsDirectory]]
500 * Dashboard: [[http://incubator.myxwiki.org/xwiki/bin/view/Improvements/GadgetsDashboard]]
501
502 === SVN ===
503
504 * Gadgets XAR Application: [[https://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/gadgets/]]
505 * Gadgets XWiki Component: [[https://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/xwiki-gadgets/]]

Get Connected