[xwiki-devs] [PROPOSAL] {{doclist}} macro syntax - [Take 1]
Hi Devs, I've been thinking about the new {{doclist}} macro syntax which is going to be the successor of old livetable macro. Following is the syntax I have in mind: {{doclist <macro_parameters>}} |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name ... {{/doclist}} [macro_parameters] class="" ## bounds the table to a class. source="" ## can be a document name or a url. (will be ignored if class parameter is set) rowCount="" ## number of rows per page. tagCloud="" ## whether to display the tag cloud or not. (On/Off) callback="" ## name of a js function to be used for handling server (JSON) response manually. [column_spec] mapping="" ## name of the json attribute to which this column should be bound to. [1] (see below) selected="" ## if this column should be selected by default. order="" ## Default sort order for this column (applies only if this is the default selected column). isHtml="" ## if the result JSON string should be treated as html and directly injected into cell content. filterable="" ## whether this column should present a filter or not. sortable="" ## whether this columnd should be sortable or not. filterType="" ## what type of a filter to be used (only for filterable columns). linkType="" ## type of link to be used if a cell value should link to the original document. [2] (see below) [1] - mapping: This is a mandatory parameter. I'm not sure if this is the correct name for the parameter. For the default implementation (XWiki.DocListMacroResults) we have to decide the names of the JSON properties that will be returned, we could use: "doc.<fieldName>" ## for document metadata. "obj.<propertyName>" ## for object properties when the table is bound to a class. "actions" ## special column for listing all the actions available for the current user. * We could have an special "function_name(field1, field2, ....)" mapping parameter which will deligate the mapping function to a local js function. This can be useful if someone wants to calculate a column value based on the returned results. * Question: Do we need to have attachment / image columns? [2] - linkType: We can have "none", "view", "edit" & "inline" type of links. Any other type of link? You can compare this doclist macro specification with the old livetable macro spec here: http://code.xwiki.org/xwiki/bin/view/Macros/LiveTableMacro. WDYT? Thanks. - Asiri
On Sep 21, 2009, at 1:58 PM, Asiri Rathnayake wrote:
Hi Devs,
I've been thinking about the new {{doclist}} macro syntax which is going to be the successor of old livetable macro.
Then there's a pb of name since doclist is about listing document but livetable is about creating a table from a JSON source. Why not name it {{livetable}}?
Following is the syntax I have in mind:
{{doclist <macro_parameters>}} |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name | =(% <column_spec> %) column_name ... {{/doclist}}
[macro_parameters]
class="" ## bounds the table to a class.
I don't think this class parameter should be here. IMO it's a special source( json source) that will do that.
source="" ## can be a document name or a url. (will be ignored if class parameter is set)
document name = document that produces json content right?
rowCount="" ## number of rows per page.
tagCloud="" ## whether to display the tag cloud or not. (On/Off)
callback="" ## name of a js function to be used for handling server (JSON) response manually.
[column_spec]
mapping="" ## name of the json attribute to which this column should be bound to. [1] (see below)
selected="" ## if this column should be selected by default.
order="" ## Default sort order for this column (applies only if this is the default selected column).
isHtml="" ## if the result JSON string should be treated as html and directly injected into cell content.
filterable="" ## whether this column should present a filter or not.
sortable="" ## whether this columnd should be sortable or not.
filterType="" ## what type of a filter to be used (only for filterable columns).
linkType="" ## type of link to be used if a cell value should link to the original document. [2] (see below)
[1] - mapping:
This is a mandatory parameter. I'm not sure if this is the correct name for the parameter. For the default implementation (XWiki.DocListMacroResults) we have to decide the names of the JSON properties that will be returned, we could use:
"doc.<fieldName>" ## for document metadata.
"obj.<propertyName>" ## for object properties when the table is bound to a class.
"actions" ## special column for listing all the actions available for the current user.
* We could have an special "function_name(field1, field2, ....)" mapping parameter which will deligate the mapping function to a local js function. This can be useful if someone wants to calculate a column value based on the returned results.
* Question: Do we need to have attachment / image columns?
[2] - linkType:
We can have "none", "view", "edit" & "inline" type of links. Any other type of link?
You can compare this doclist macro specification with the old livetable macro spec here: http://code.xwiki.org/xwiki/bin/view/Macros/LiveTableMacro .
WDYT?
sounds good I'd like to see also some predefined macros that would use the livetable macro. I can think of: - a {{objects}} macro that would display a livetable of objects matching a given xclass - a {{documents}} macro that would display a livetable of documents matching a query Thanks -Vincent
Thanks.
- Asiri
I'd also like to know if we can support the use case of having a normal table for which we'd like to do filtering/sorting. Could that be a special {{table}} macro that would use the {{livetable}} macro with a special source that takes the content of the {{table}} macro as the content to be displayed and extract from it both the content and the table definition? Thanks -Vincent On Sep 21, 2009, at 2:22 PM, Vincent Massol wrote:
On Sep 21, 2009, at 1:58 PM, Asiri Rathnayake wrote:
Hi Devs,
I've been thinking about the new {{doclist}} macro syntax which is going to be the successor of old livetable macro.
Then there's a pb of name since doclist is about listing document but livetable is about creating a table from a JSON source.
Why not name it {{livetable}}?
Following is the syntax I have in mind:
{{doclist <macro_parameters>}} |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name ... {{/doclist}}
[macro_parameters]
class="" ## bounds the table to a class.
I don't think this class parameter should be here. IMO it's a special source( json source) that will do that.
source="" ## can be a document name or a url. (will be ignored if class parameter is set)
document name = document that produces json content right?
rowCount="" ## number of rows per page.
tagCloud="" ## whether to display the tag cloud or not. (On/Off)
callback="" ## name of a js function to be used for handling server (JSON) response manually.
[column_spec]
mapping="" ## name of the json attribute to which this column should be bound to. [1] (see below)
selected="" ## if this column should be selected by default.
order="" ## Default sort order for this column (applies only if this is the default selected column).
isHtml="" ## if the result JSON string should be treated as html and directly injected into cell content.
filterable="" ## whether this column should present a filter or not.
sortable="" ## whether this columnd should be sortable or not.
filterType="" ## what type of a filter to be used (only for filterable columns).
linkType="" ## type of link to be used if a cell value should link to the original document. [2] (see below)
[1] - mapping:
This is a mandatory parameter. I'm not sure if this is the correct name for the parameter. For the default implementation (XWiki.DocListMacroResults) we have to decide the names of the JSON properties that will be returned, we could use:
"doc.<fieldName>" ## for document metadata.
"obj.<propertyName>" ## for object properties when the table is bound to a class.
"actions" ## special column for listing all the actions available for the current user.
* We could have an special "function_name(field1, field2, ....)" mapping parameter which will deligate the mapping function to a local js function. This can be useful if someone wants to calculate a column value based on the returned results.
* Question: Do we need to have attachment / image columns?
[2] - linkType:
We can have "none", "view", "edit" & "inline" type of links. Any other type of link?
You can compare this doclist macro specification with the old livetable macro spec here: http://code.xwiki.org/xwiki/bin/view/Macros/LiveTableMacro .
WDYT?
sounds good
I'd like to see also some predefined macros that would use the livetable macro. I can think of:
- a {{objects}} macro that would display a livetable of objects matching a given xclass - a {{documents}} macro that would display a livetable of documents matching a query
Thanks -Vincent
Thanks.
- Asiri
Hi, On Mon, Sep 21, 2009 at 6:07 PM, Vincent Massol <[email protected]> wrote:
I'd also like to know if we can support the use case of having a normal table for which we'd like to do filtering/sorting.
Could that be a special {{table}} macro that would use the {{livetable}} macro with a special source that takes the content of the {{table}} macro as the content to be displayed and extract from it both the content and the table definition?
I think it's better to keep the livetable macro as I defined earlier (dynamically fetch json...). This way it will have a specific meaning. If we are to make livetable macro support this usecase, we have to either: 1. Make livetable macro even more generic. 2. Stuff up livetable macro which will enable this usecase. I can't think of a reasonable approach to achieve 1) and 2) is bad. What we need for this usecase is may be a {{dynamictable}} macro like http://confluence.atlassian.com/display/CONFEXT/Dynamic+Table+Macro Thanks. - Asiri
On Sep 21, 2009, at 4:33 PM, Asiri Rathnayake wrote:
Hi,
On Mon, Sep 21, 2009 at 6:07 PM, Vincent Massol <[email protected]> wrote:
I'd also like to know if we can support the use case of having a normal table for which we'd like to do filtering/sorting.
Could that be a special {{table}} macro that would use the {{livetable}} macro with a special source that takes the content of the {{table}} macro as the content to be displayed and extract from it both the content and the table definition?
I think it's better to keep the livetable macro as I defined earlier (dynamically fetch json...). This way it will have a specific meaning. If we are to make livetable macro support this usecase, we have to either:
1. Make livetable macro even more generic.
2. Stuff up livetable macro which will enable this usecase.
I can't think of a reasonable approach to achieve 1) and 2) is bad.
My though was that the implementation of {{table}} would generate 2 things: - a {{livetable}} macro with the content being the definition of columns extracted from the {{table}} contnet - calls a generic special JSON source that knows how to extract data from a given document and a given table id (that's relatively easy using the XDOM information) -Vincent
What we need for this usecase is may be a {{dynamictable}} macro like http://confluence.atlassian.com/display/CONFEXT/Dynamic+Table+Macro
Thanks.
- Asiri
On Sep 21, 2009, at 4:42 PM, Vincent Massol wrote:
On Sep 21, 2009, at 4:33 PM, Asiri Rathnayake wrote:
Hi,
On Mon, Sep 21, 2009 at 6:07 PM, Vincent Massol <[email protected]> wrote:
I'd also like to know if we can support the use case of having a normal table for which we'd like to do filtering/sorting.
Could that be a special {{table}} macro that would use the {{livetable}} macro with a special source that takes the content of the {{table}} macro as the content to be displayed and extract from it both the content and the table definition?
I think it's better to keep the livetable macro as I defined earlier (dynamically fetch json...). This way it will have a specific meaning. If we are to make livetable macro support this usecase, we have to either:
1. Make livetable macro even more generic.
2. Stuff up livetable macro which will enable this usecase.
I can't think of a reasonable approach to achieve 1) and 2) is bad.
My though was that the implementation of {{table}} would generate 2 things: - a {{livetable}} macro with the content being the definition of columns extracted from the {{table}} contnet - calls a generic special JSON source that knows how to extract data from a given document and a given table id (that's relatively easy using the XDOM information)
or pass the full {{table}} macro content to the special JSON source which is better since we don't need to use table ids. -Vincent
What we need for this usecase is may be a {{dynamictable}} macro like http://confluence.atlassian.com/display/CONFEXT/Dynamic+Table+Macro
Thanks.
- Asiri
Hi,
My though was that the implementation of {{table}} would generate 2
things: - a {{livetable}} macro with the content being the definition of columns extracted from the {{table}} contnet - calls a generic special JSON source that knows how to extract data from a given document and a given table id (that's relatively easy using the XDOM information)
or pass the full {{table}} macro content to the special JSON source which is better since we don't need to use table ids.
Sounds good. This way we can treat {{table}} macro as an extension of {{livetable}} macro and keep the {{livetable}} macro definition simple. Thanks. - Asiri
-Vincent
What we need for this usecase is may be a {{dynamictable}} macro like http://confluence.atlassian.com/display/CONFEXT/Dynamic+Table+Macro
Thanks.
- Asiri
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Vincent Massol wrote: > On Sep 21, 2009, at 4:42 PM, Vincent Massol wrote: > >> On Sep 21, 2009, at 4:33 PM, Asiri Rathnayake wrote: >> >>> Hi, >>> >>> On Mon, Sep 21, 2009 at 6:07 PM, Vincent Massol >>> <[email protected]> wrote: >>> >>>> I'd also like to know if we can support the use case of having a >>>> normal table for which we'd like to do filtering/sorting. >>>> >>>> Could that be a special {{table}} macro that would use the >>>> {{livetable}} macro with a special source that takes the content of >>>> the {{table}} macro as the content to be displayed and extract >>>> from it >>>> both the content and the table definition? >>>> >>> I think it's better to keep the livetable macro as I defined earlier >>> (dynamically fetch json...). This way it will have a specific >>> meaning. If we >>> are to make livetable macro support this usecase, we have to either: >>> >>> 1. Make livetable macro even more generic. >>> 2. Stuff up livetable macro which will enable this usecase. >>> I can't think of a reasonable approach to achieve 1) and 2) is bad. >> My though was that the implementation of {{table}} would generate 2 >> things: >> - a {{livetable}} macro with the content being the definition of >> columns extracted from the {{table}} contnet >> - calls a generic special JSON source that knows how to extract data >> from a given document and a given table id (that's relatively easy >> using the XDOM information) > > or pass the full {{table}} macro content to the special JSON source > which is better since we don't need to use table ids. This can be done using the POST data of the AJAX requests to the source. Jerome. > > -Vincent > >>> What we need for this usecase is may be a {{dynamictable}} macro like >>> http://confluence.atlassian.com/display/CONFEXT/Dynamic+Table+Macro >>> >>> Thanks. >>> >>> - Asiri > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs
Hi Vincent & Thomas, Thanks for the feedback. I wasn't sure about how generic we want our new "livetable" macro to be. From our discussions in http://n2.nabble.com/HELP-LiveTable-2-0-Macro-td3662035.html what I understood is that main purpose of livetable macro is to act as a method for listing documents. Now, if we expand the scope of livetable 2.0 macro to: "dynamically fetch a json object from a url (or a document) and layout that content in a table like structure" Then we can resolve to following generic syntax: {{livetable source="" params=""}}....{{/livetable}} "source" can be a url or an xwiki document name (producing json) and params will be fed into this url. Now based on this syntax we can derive sub-macros like: {{documents}} & {{objects}} which will internally use the generic {{livetable}} macro. WDYT? Thanks. - Asiri
On Mon, Sep 21, 2009 at 16:28, Asiri Rathnayake <[email protected]> wrote:
Hi Vincent & Thomas,
Thanks for the feedback. I wasn't sure about how generic we want our new "livetable" macro to be. From our discussions in http://n2.nabble.com/HELP-LiveTable-2-0-Macro-td3662035.html what I understood is that main purpose of livetable macro is to act as a method for listing documents.
Now, if we expand the scope of livetable 2.0 macro to:
"dynamically fetch a json object from a url (or a document) and layout that content in a table like structure"
Then we can resolve to following generic syntax:
{{livetable source="" params=""}}....{{/livetable}}
"source" can be a url or an xwiki document name (producing json) and params will be fed into this url.
Now based on this syntax we can derive sub-macros like:
{{documents}} & {{objects}} which will internally use the generic {{livetable}} macro.
WDYT?
Sounds good to me.
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Mon, Sep 21, 2009 at 13:58, Asiri Rathnayake <[email protected]> wrote:
Hi Devs,
I've been thinking about the new {{doclist}} macro syntax which is going to be the successor of old livetable macro.
This name is wrong. List documents is just one use case among others and not even the most common one in XE.
Following is the syntax I have in mind:
{{doclist <macro_parameters>}} |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name ... {{/doclist}}
[macro_parameters]
class="" ## bounds the table to a class.
Again this is just one use case, we should have some sort generic parameters we want to give to the source instead of this arbitrary parameter that not always means something. Like sourceParameters="key1=value1" (I think ConvertUtils support Map conversion and if not it's easy to add one) to be able to use any parameter or give to the source all unknown parameters (we can also do both).
source="" ## can be a document name or a url. (will be ignored if class parameter is set)
rowCount="" ## number of rows per page.
tagCloud="" ## whether to display the tag cloud or not. (On/Off)
callback="" ## name of a js function to be used for handling server (JSON) response manually.
[column_spec]
mapping="" ## name of the json attribute to which this column should be bound to. [1] (see below)
selected="" ## if this column should be selected by default.
order="" ## Default sort order for this column (applies only if this is the default selected column).
isHtml="" ## if the result JSON string should be treated as html and directly injected into cell content.
filterable="" ## whether this column should present a filter or not.
sortable="" ## whether this columnd should be sortable or not.
filterType="" ## what type of a filter to be used (only for filterable columns).
linkType="" ## type of link to be used if a cell value should link to the original document. [2] (see below)
[1] - mapping:
This is a mandatory parameter. I'm not sure if this is the correct name for the parameter. For the default implementation (XWiki.DocListMacroResults) we have to decide the names of the JSON properties that will be returned, we could use:
"doc.<fieldName>" ## for document metadata.
"obj.<propertyName>" ## for object properties when the table is bound to a class.
"actions" ## special column for listing all the actions available for the current user.
* We could have an special "function_name(field1, field2, ....)" mapping parameter which will deligate the mapping function to a local js function. This can be useful if someone wants to calculate a column value based on the returned results.
* Question: Do we need to have attachment / image columns?
[2] - linkType:
We can have "none", "view", "edit" & "inline" type of links. Any other type of link?
You can compare this doclist macro specification with the old livetable macro spec here: http://code.xwiki.org/xwiki/bin/view/Macros/LiveTableMacro.
WDYT?
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
Hi Asiri, Asiri Rathnayake wrote:
Hi Devs,
I've been thinking about the new {{doclist}} macro syntax which is going to be the successor of old livetable macro.
Following is the syntax I have in mind:
{{doclist <macro_parameters>}} |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name ... {{/doclist}}
[macro_parameters]
class="" ## bounds the table to a class.
source="" ## can be a document name or a url. (will be ignored if class parameter is set)
rowCount="" ## number of rows per page.
tagCloud="" ## whether to display the tag cloud or not. (On/Off)
callback="" ## name of a js function to be used for handling server (JSON) response manually.
I don't think we want to expose that. This is too technical. An idea for extensibility/custom columns would be use JS events instead. (fired before the row is injected in the table for example).
[column_spec]
mapping="" ## name of the json attribute to which this column should be bound to. [1] (see below)
IMHO the mapping should not be mandatory (as in the current velocity livetable macro), and should be extracted from column name if not specified. Thanks, Jerome.
selected="" ## if this column should be selected by default.
order="" ## Default sort order for this column (applies only if this is the default selected column).
isHtml="" ## if the result JSON string should be treated as html and directly injected into cell content.
filterable="" ## whether this column should present a filter or not.
sortable="" ## whether this columnd should be sortable or not.
filterType="" ## what type of a filter to be used (only for filterable columns).
linkType="" ## type of link to be used if a cell value should link to the original document. [2] (see below)
[1] - mapping:
This is a mandatory parameter. I'm not sure if this is the correct name for the parameter. For the default implementation (XWiki.DocListMacroResults) we have to decide the names of the JSON properties that will be returned, we could use:
"doc.<fieldName>" ## for document metadata.
"obj.<propertyName>" ## for object properties when the table is bound to a class.
"actions" ## special column for listing all the actions available for the current user.
* We could have an special "function_name(field1, field2, ....)" mapping parameter which will deligate the mapping function to a local js function. This can be useful if someone wants to calculate a column value based on the returned results.
* Question: Do we need to have attachment / image columns?
[2] - linkType:
We can have "none", "view", "edit" & "inline" type of links. Any other type of link?
You can compare this doclist macro specification with the old livetable macro spec here: http://code.xwiki.org/xwiki/bin/view/Macros/LiveTableMacro.
WDYT?
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
BTW, it would be good that the callback supports the JSON given by our REST API natively. I think the base versions (like {{documents}}, {{objects}}) should consume REST resources. We could decide that the livetable only consumes REST, but that would be a strong limitation compared to what the velocity livetable can do today. In my opinion, the challenge is to support both REST and non-REST JSON sources. Jerome. Asiri Rathnayake wrote:
Hi Devs,
I've been thinking about the new {{doclist}} macro syntax which is going to be the successor of old livetable macro.
Following is the syntax I have in mind:
{{doclist <macro_parameters>}} |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name |=(% <column_spec> %) column_name ... {{/doclist}}
[macro_parameters]
class="" ## bounds the table to a class.
source="" ## can be a document name or a url. (will be ignored if class parameter is set)
rowCount="" ## number of rows per page.
tagCloud="" ## whether to display the tag cloud or not. (On/Off)
callback="" ## name of a js function to be used for handling server (JSON) response manually.
[column_spec]
mapping="" ## name of the json attribute to which this column should be bound to. [1] (see below)
selected="" ## if this column should be selected by default.
order="" ## Default sort order for this column (applies only if this is the default selected column).
isHtml="" ## if the result JSON string should be treated as html and directly injected into cell content.
filterable="" ## whether this column should present a filter or not.
sortable="" ## whether this columnd should be sortable or not.
filterType="" ## what type of a filter to be used (only for filterable columns).
linkType="" ## type of link to be used if a cell value should link to the original document. [2] (see below)
[1] - mapping:
This is a mandatory parameter. I'm not sure if this is the correct name for the parameter. For the default implementation (XWiki.DocListMacroResults) we have to decide the names of the JSON properties that will be returned, we could use:
"doc.<fieldName>" ## for document metadata.
"obj.<propertyName>" ## for object properties when the table is bound to a class.
"actions" ## special column for listing all the actions available for the current user.
* We could have an special "function_name(field1, field2, ....)" mapping parameter which will deligate the mapping function to a local js function. This can be useful if someone wants to calculate a column value based on the returned results.
* Question: Do we need to have attachment / image columns?
[2] - linkType:
We can have "none", "view", "edit" & "inline" type of links. Any other type of link?
You can compare this doclist macro specification with the old livetable macro spec here: http://code.xwiki.org/xwiki/bin/view/Macros/LiveTableMacro.
WDYT?
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
participants (4)
-
Asiri Rathnayake -
Jerome Velociter -
Thomas Mortagne -
Vincent Massol