[xwiki-devs] [DESIGN][PROPOSAL] Macro Categories Implementation
Hi, I would like to introduce a MacroCategoriesManager component for managing macro categories. We already have a MacroManager component in place but I think seperating out the concern of macro categories management into a seperate component creates a more extensible design. Following is a basic outline for implementing MacroCategoriesManager component: * Introduce MacroDescriptor::getDefaultCategory() method which returns a String. The purpose of this method is to allow macro author to supply a default category under which his macro should be listed. This method can virtually return any string. Following three steps I'm not very confident about: * Duplicate each existing constructor in AbstractMacro and add a 'category' parameter. * Make AbstractMacroDescriptor constructor accept a 'category' parameter. * Duplicate each existing constructor in DefaultMacroDescriptor and add a 'category' parameter. If a macro author does not specify a default category, the "Other" category will be used. * Introduce the MacroCategoriesManager component with following methods: List<String> getMacroCategories() List<String> getMacroNames(String category) List<String> getMacroNames(String category, Syntax syntax) Each of these methods will give priority to admin configured macro categories. That is they will discard MacroDescriptor::getDefaultCategory() return value if the wiki admin has configured a different category for a given macro. * A macro category can be overwritten by specifying the configuration parameter "org.xwiki.rendering.macro.<macro_name>.category" using xwiki's configuration mechanism (Ex. xwiki.properties). This is my initial design idea, please let me know what you think. Thanks. - Asiri
On Tue, Aug 4, 2009 at 18:53, Asiri Rathnayake<[email protected]> wrote:
Hi,
I would like to introduce a MacroCategoriesManager component for managing macro categories. We already have a MacroManager component in place but I think seperating out the concern of macro categories management into a seperate component creates a more extensible design. Following is a basic outline for implementing MacroCategoriesManager component:
* Introduce MacroDescriptor::getDefaultCategory() method which returns a String. The purpose of this method is to allow macro author to supply a default category under which his macro should be listed. This method can virtually return any string.
Following three steps I'm not very confident about:
* Duplicate each existing constructor in AbstractMacro and add a 'category' parameter.
* Make AbstractMacroDescriptor constructor accept a 'category' parameter.
* Duplicate each existing constructor in DefaultMacroDescriptor and add a 'category' parameter.
If a macro author does not specify a default category, the "Other" category will be used.
Where do you plan to decide for "Other" string ? IMO it's should not be the default value of the field containing the category in AbtractMacro, you should know that a macro did not defined any category to let the user of the api decide what it does with macro without category, the way we do in the WYSIYWG is just one way, you could decide that a macro without category is not listed or is listed visualy at the same level of the categories etc... At rendering midule level you just need to know that a macro does not have any category, the choice of the default category is made by the presentation side. Just to make sure since it's not very clear in your proposal.
* Introduce the MacroCategoriesManager component with following methods:
List<String> getMacroCategories()
List<String> getMacroNames(String category)
List<String> getMacroNames(String category, Syntax syntax)
Why not return a list of Macro instead of just the names ? It would be more consistent with MacroManager.
Each of these methods will give priority to admin configured macro categories. That is they will discard MacroDescriptor::getDefaultCategory() return value if the wiki admin has configured a different category for a given macro.
* A macro category can be overwritten by specifying the configuration parameter "org.xwiki.rendering.macro.<macro_name>.category" using xwiki's configuration mechanism (Ex. xwiki.properties).
This is my initial design idea, please let me know what you think.
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Wed, Aug 5, 2009 at 14:35, Thomas Mortagne<[email protected]> wrote:
On Tue, Aug 4, 2009 at 18:53, Asiri Rathnayake<[email protected]> wrote:
Hi,
I would like to introduce a MacroCategoriesManager component for managing macro categories. We already have a MacroManager component in place but I think seperating out the concern of macro categories management into a seperate component creates a more extensible design. Following is a basic outline for implementing MacroCategoriesManager component:
* Introduce MacroDescriptor::getDefaultCategory() method which returns a String. The purpose of this method is to allow macro author to supply a default category under which his macro should be listed. This method can virtually return any string.
Following three steps I'm not very confident about:
* Duplicate each existing constructor in AbstractMacro and add a 'category' parameter.
* Make AbstractMacroDescriptor constructor accept a 'category' parameter.
* Duplicate each existing constructor in DefaultMacroDescriptor and add a 'category' parameter.
If a macro author does not specify a default category, the "Other" category will be used.
Where do you plan to decide for "Other" string ? IMO it's should not be the default value of the field containing the category in AbtractMacro, you should know that a macro did not defined any category to let the user of the api decide what it does with macro without category, the way we do in the WYSIYWG is just one way, you could decide that a macro without category is not listed or is listed visualy at the same level of the categories etc... At rendering midule level you just need to know that a macro does not have any category, the choice of the default category is made by the presentation side.
Just to make sure since it's not very clear in your proposal.
* Introduce the MacroCategoriesManager component with following methods:
List<String> getMacroCategories()
List<String> getMacroNames(String category)
List<String> getMacroNames(String category, Syntax syntax)
Why not return a list of Macro instead of just the names ? It would be more consistent with MacroManager.
Actually forget that, i did not remember that Macro does not know its own name.
Each of these methods will give priority to admin configured macro categories. That is they will discard MacroDescriptor::getDefaultCategory() return value if the wiki admin has configured a different category for a given macro.
* A macro category can be overwritten by specifying the configuration parameter "org.xwiki.rendering.macro.<macro_name>.category" using xwiki's configuration mechanism (Ex. xwiki.properties).
This is my initial design idea, please let me know what you think.
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Thomas Mortagne
Hi, On Wed, Aug 5, 2009 at 6:05 PM, Thomas Mortagne <[email protected]>wrote:
On Tue, Aug 4, 2009 at 18:53, Asiri Rathnayake<[email protected]> wrote:
Hi,
I would like to introduce a MacroCategoriesManager component for managing macro categories. We already have a MacroManager component in place but I think seperating out the concern of macro categories management into a seperate component creates a more extensible design. Following is a basic outline for implementing MacroCategoriesManager component:
* Introduce MacroDescriptor::getDefaultCategory() method which returns a String. The purpose of this method is to allow macro author to supply a default category under which his macro should be listed. This method can virtually return any string.
Following three steps I'm not very confident about:
* Duplicate each existing constructor in AbstractMacro and add a 'category' parameter.
* Make AbstractMacroDescriptor constructor accept a 'category' parameter.
* Duplicate each existing constructor in DefaultMacroDescriptor and add a 'category' parameter.
If a macro author does not specify a default category, the "Other" category will be used.
Where do you plan to decide for "Other" string ? IMO it's should not be the default value of the field containing the category in AbtractMacro, you should know that a macro did not defined any category to let the user of the api decide what it does with macro without category, the way we do in the WYSIYWG is just one way, you could decide that a macro without category is not listed or is listed visualy at the same level of the categories etc... At rendering midule level you just need to know that a macro does not have any category, the choice of the default category is made by the presentation side.
The other sensible way to indicate a macro without a category is to return "null" in getCategory() method. But the problem with this is it is hard to expose such macros through MacroCategoriesManager in a sensible way: * We could have a Set<String> getMacrosWithoutCategory() method * Or we can allow client code to pass "null" as an argument to getMacroNames(String category) method. IMO the second method is not explicit enough and the first method seems like an overkill. WDYT? Thanks. - Asiri
Just to make sure since it's not very clear in your proposal.
* Introduce the MacroCategoriesManager component with following methods:
List<String> getMacroCategories()
List<String> getMacroNames(String category)
List<String> getMacroNames(String category, Syntax syntax)
Why not return a list of Macro instead of just the names ? It would be more consistent with MacroManager.
Each of these methods will give priority to admin configured macro categories. That is they will discard
MacroDescriptor::getDefaultCategory()
return value if the wiki admin has configured a different category for a given macro.
* A macro category can be overwritten by specifying the configuration parameter "org.xwiki.rendering.macro.<macro_name>.category" using xwiki's configuration mechanism (Ex. xwiki.properties).
This is my initial design idea, please let me know what you think.
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Wed, Aug 5, 2009 at 19:30, Asiri Rathnayake<[email protected]> wrote:
Hi,
On Wed, Aug 5, 2009 at 6:05 PM, Thomas Mortagne <[email protected]>wrote:
On Tue, Aug 4, 2009 at 18:53, Asiri Rathnayake<[email protected]> wrote:
Hi,
I would like to introduce a MacroCategoriesManager component for managing macro categories. We already have a MacroManager component in place but I think seperating out the concern of macro categories management into a seperate component creates a more extensible design. Following is a basic outline for implementing MacroCategoriesManager component:
* Introduce MacroDescriptor::getDefaultCategory() method which returns a String. The purpose of this method is to allow macro author to supply a default category under which his macro should be listed. This method can virtually return any string.
Following three steps I'm not very confident about:
* Duplicate each existing constructor in AbstractMacro and add a 'category' parameter.
* Make AbstractMacroDescriptor constructor accept a 'category' parameter.
* Duplicate each existing constructor in DefaultMacroDescriptor and add a 'category' parameter.
If a macro author does not specify a default category, the "Other" category will be used.
Where do you plan to decide for "Other" string ? IMO it's should not be the default value of the field containing the category in AbtractMacro, you should know that a macro did not defined any category to let the user of the api decide what it does with macro without category, the way we do in the WYSIYWG is just one way, you could decide that a macro without category is not listed or is listed visualy at the same level of the categories etc... At rendering midule level you just need to know that a macro does not have any category, the choice of the default category is made by the presentation side.
The other sensible way to indicate a macro without a category is to return "null" in getCategory() method. But the problem with this is it is hard to expose such macros through MacroCategoriesManager in a sensible way:
* We could have a Set<String> getMacrosWithoutCategory() method
* Or we can allow client code to pass "null" as an argument to getMacroNames(String category) method.
IMO the second method is not explicit enough and the first method seems like an overkill.
I think both solutions are better than some random String which make impossible to know that a macro does not have category.
WDYT?
Thanks.
- Asiri
Just to make sure since it's not very clear in your proposal.
* Introduce the MacroCategoriesManager component with following methods:
List<String> getMacroCategories()
List<String> getMacroNames(String category)
List<String> getMacroNames(String category, Syntax syntax)
Why not return a list of Macro instead of just the names ? It would be more consistent with MacroManager.
Each of these methods will give priority to admin configured macro categories. That is they will discard
MacroDescriptor::getDefaultCategory()
return value if the wiki admin has configured a different category for a given macro.
* A macro category can be overwritten by specifying the configuration parameter "org.xwiki.rendering.macro.<macro_name>.category" using xwiki's configuration mechanism (Ex. xwiki.properties).
This is my initial design idea, please let me know what you think.
Thanks.
- Asiri _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
participants (2)
-
Asiri Rathnayake -
Thomas Mortagne