[Proposal] Add a new method in the icon API

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposal] Add a new method in the icon API

Adel Atallah
Hi devs,

I'm making a rest resource to get a list of pages and, for a query, I
want to specify an icon (as a metadata) for each pages in the resulted
json.
The problem is that the icon APIs (and more specifically the
IconManager class) only allow us to render the icon in HTML or
velocity and this shouldn't be put inside a json response.
Also we can't hardcode the icon class or image URL to be used as it
depends on the iconset configured for the wiki. Another possibility
would be to render the icon using javascript but it will not be very
efficient.

As discussed with Marius, our proposal would be to add a new method to
the IconManager to get either the icon URL (e.g.
http://xwiki.org/xwiki/resources/icons/silk/page.png) or the icon
class (e.g. fa fa-page) depending of the specified iconset.
We could then have this new property to the icon theme definition:

## Silk
xwiki.iconset.render.json=$xwiki.getSkinFile("icons/silk/${icon}.png")
## FontAwesome
xwiki.iconset.render.json=fa fa-$icon

We could name the new method renderJSON or something more generic (if
you have any idea).


WDYT?

Thanks,
Adel
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Add a new method in the icon API

Ecaterina Moraru (Valica)
xwiki.iconset.render.json sounds good. The only thing is that render.wiki
and render.html contain valid specific syntax (if you get over Velocity),
while "fa fa-$icon" will not be JSON valid. But I guess it will simpler to
declare it like this, than to provide it more explicit.

Thanks,
Caty

On Thu, Jun 14, 2018 at 12:56 PM, Adel Atallah <[hidden email]>
wrote:

> Hi devs,
>
> I'm making a rest resource to get a list of pages and, for a query, I
> want to specify an icon (as a metadata) for each pages in the resulted
> json.
> The problem is that the icon APIs (and more specifically the
> IconManager class) only allow us to render the icon in HTML or
> velocity and this shouldn't be put inside a json response.
> Also we can't hardcode the icon class or image URL to be used as it
> depends on the iconset configured for the wiki. Another possibility
> would be to render the icon using javascript but it will not be very
> efficient.
>
> As discussed with Marius, our proposal would be to add a new method to
> the IconManager to get either the icon URL (e.g.
> http://xwiki.org/xwiki/resources/icons/silk/page.png) or the icon
> class (e.g. fa fa-page) depending of the specified iconset.
> We could then have this new property to the icon theme definition:
>
> ## Silk
> xwiki.iconset.render.json=$xwiki.getSkinFile("icons/silk/${icon}.png")
> ## FontAwesome
> xwiki.iconset.render.json=fa fa-$icon
>
> We could name the new method renderJSON or something more generic (if
> you have any idea).
>
>
> WDYT?
>
> Thanks,
> Adel
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Add a new method in the icon API

Marius Dumitru Florea
In reply to this post by Adel Atallah
+1 obviously.

I encountered this need multiple times. One such example is the Document
Tree which uses the jstree library which accepts as node icon an URL, a
path or a CSS class name. I believe it is common in the JavaScript world to
be able to specify an icon either as an URL/path or as a CSS icon. The
reason Adel proposed "renderJSON" is because this method is needed mainly
when you generate JSON and the client that receives the JSON wants to have
100% control over the HTML that is generated (so injecting the HTML we get
from renderHTML is not an option).

Note that besides renderJSON we would also need a method to pull the
resources required by the icon set. I propose something like:

$services.icon.use() <--- pull the resources for the configured icon set
$services.icon.use('someIconSet') <--- pull the resources for the specified
icon set

These methods will call ssx, jsx, etc. under the hood. This is done already
when you call render() and renderHTML() but it obviously doesn't work if
you call render* on an AJAX request that returns JSON.

Thanks,
Marius


On Thu, Jun 14, 2018 at 12:56 PM, Adel Atallah <[hidden email]>
wrote:

> Hi devs,
>
> I'm making a rest resource to get a list of pages and, for a query, I
> want to specify an icon (as a metadata) for each pages in the resulted
> json.
> The problem is that the icon APIs (and more specifically the
> IconManager class) only allow us to render the icon in HTML or
> velocity and this shouldn't be put inside a json response.
> Also we can't hardcode the icon class or image URL to be used as it
> depends on the iconset configured for the wiki. Another possibility
> would be to render the icon using javascript but it will not be very
> efficient.
>
> As discussed with Marius, our proposal would be to add a new method to
> the IconManager to get either the icon URL (e.g.
> http://xwiki.org/xwiki/resources/icons/silk/page.png) or the icon
> class (e.g. fa fa-page) depending of the specified iconset.
> We could then have this new property to the icon theme definition:
>
> ## Silk
> xwiki.iconset.render.json=$xwiki.getSkinFile("icons/silk/${icon}.png")
> ## FontAwesome
> xwiki.iconset.render.json=fa fa-$icon
>
> We could name the new method renderJSON or something more generic (if
> you have any idea).
>
>
> WDYT?
>
> Thanks,
> Adel
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Add a new method in the icon API

Adel Atallah
Another idea would be to add a 'getMetaData()' method to the API
(instead of renderJSON) which would take the same arguments as
'render()' and 'renderHTML()' methods and would return a map with some
metadata, particularly the url of the image or the css class depending
of the chosen iconset. This way, we won't even need to parse a string
to know if the icon should be rendered as an image or with a css
class, we will just need to check for the presence of some key in the
map. We will also be able add other useful information in the future
as well.

We will still need the '$services.icon.use()' methods as described by
Marius to pull the necessary resources.

Thanks,
Adel


On Thu, Jun 14, 2018 at 1:24 PM, Marius Dumitru Florea
<[hidden email]> wrote:

> +1 obviously.
>
> I encountered this need multiple times. One such example is the Document
> Tree which uses the jstree library which accepts as node icon an URL, a
> path or a CSS class name. I believe it is common in the JavaScript world to
> be able to specify an icon either as an URL/path or as a CSS icon. The
> reason Adel proposed "renderJSON" is because this method is needed mainly
> when you generate JSON and the client that receives the JSON wants to have
> 100% control over the HTML that is generated (so injecting the HTML we get
> from renderHTML is not an option).
>
> Note that besides renderJSON we would also need a method to pull the
> resources required by the icon set. I propose something like:
>
> $services.icon.use() <--- pull the resources for the configured icon set
> $services.icon.use('someIconSet') <--- pull the resources for the specified
> icon set
>
> These methods will call ssx, jsx, etc. under the hood. This is done already
> when you call render() and renderHTML() but it obviously doesn't work if
> you call render* on an AJAX request that returns JSON.
>
> Thanks,
> Marius
>
>
> On Thu, Jun 14, 2018 at 12:56 PM, Adel Atallah <[hidden email]>
> wrote:
>
>> Hi devs,
>>
>> I'm making a rest resource to get a list of pages and, for a query, I
>> want to specify an icon (as a metadata) for each pages in the resulted
>> json.
>> The problem is that the icon APIs (and more specifically the
>> IconManager class) only allow us to render the icon in HTML or
>> velocity and this shouldn't be put inside a json response.
>> Also we can't hardcode the icon class or image URL to be used as it
>> depends on the iconset configured for the wiki. Another possibility
>> would be to render the icon using javascript but it will not be very
>> efficient.
>>
>> As discussed with Marius, our proposal would be to add a new method to
>> the IconManager to get either the icon URL (e.g.
>> http://xwiki.org/xwiki/resources/icons/silk/page.png) or the icon
>> class (e.g. fa fa-page) depending of the specified iconset.
>> We could then have this new property to the icon theme definition:
>>
>> ## Silk
>> xwiki.iconset.render.json=$xwiki.getSkinFile("icons/silk/${icon}.png")
>> ## FontAwesome
>> xwiki.iconset.render.json=fa fa-$icon
>>
>> We could name the new method renderJSON or something more generic (if
>> you have any idea).
>>
>>
>> WDYT?
>>
>> Thanks,
>> Adel
>>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Add a new method in the icon API

Marius Dumitru Florea
On Fri, Jun 15, 2018 at 12:18 PM, Adel Atallah <[hidden email]>
wrote:

> Another idea would be to add a 'getMetaData()' method to the API
> (instead of renderJSON) which would take the same arguments as
> 'render()' and 'renderHTML()' methods and would return a map with some
> metadata, particularly the url of the image or the css class depending
> of the chosen iconset. This way, we won't even need to parse a string
> to know if the icon should be rendered as an image or with a css
> class, we will just need to check for the presence of some key in the
> map. We will also be able add other useful information in the future
> as well.
>

+1


>
> We will still need the '$services.icon.use()' methods as described by
> Marius to pull the necessary resources.
>
> Thanks,
> Adel
>
>
> On Thu, Jun 14, 2018 at 1:24 PM, Marius Dumitru Florea
> <[hidden email]> wrote:
> > +1 obviously.
> >
> > I encountered this need multiple times. One such example is the Document
> > Tree which uses the jstree library which accepts as node icon an URL, a
> > path or a CSS class name. I believe it is common in the JavaScript world
> to
> > be able to specify an icon either as an URL/path or as a CSS icon. The
> > reason Adel proposed "renderJSON" is because this method is needed mainly
> > when you generate JSON and the client that receives the JSON wants to
> have
> > 100% control over the HTML that is generated (so injecting the HTML we
> get
> > from renderHTML is not an option).
> >
> > Note that besides renderJSON we would also need a method to pull the
> > resources required by the icon set. I propose something like:
> >
> > $services.icon.use() <--- pull the resources for the configured icon set
> > $services.icon.use('someIconSet') <--- pull the resources for the
> specified
> > icon set
> >
> > These methods will call ssx, jsx, etc. under the hood. This is done
> already
> > when you call render() and renderHTML() but it obviously doesn't work if
> > you call render* on an AJAX request that returns JSON.
> >
> > Thanks,
> > Marius
> >
> >
> > On Thu, Jun 14, 2018 at 12:56 PM, Adel Atallah <[hidden email]>
> > wrote:
> >
> >> Hi devs,
> >>
> >> I'm making a rest resource to get a list of pages and, for a query, I
> >> want to specify an icon (as a metadata) for each pages in the resulted
> >> json.
> >> The problem is that the icon APIs (and more specifically the
> >> IconManager class) only allow us to render the icon in HTML or
> >> velocity and this shouldn't be put inside a json response.
> >> Also we can't hardcode the icon class or image URL to be used as it
> >> depends on the iconset configured for the wiki. Another possibility
> >> would be to render the icon using javascript but it will not be very
> >> efficient.
> >>
> >> As discussed with Marius, our proposal would be to add a new method to
> >> the IconManager to get either the icon URL (e.g.
> >> http://xwiki.org/xwiki/resources/icons/silk/page.png) or the icon
> >> class (e.g. fa fa-page) depending of the specified iconset.
> >> We could then have this new property to the icon theme definition:
> >>
> >> ## Silk
> >> xwiki.iconset.render.json=$xwiki.getSkinFile("icons/silk/${icon}.png")
> >> ## FontAwesome
> >> xwiki.iconset.render.json=fa fa-$icon
> >>
> >> We could name the new method renderJSON or something more generic (if
> >> you have any idea).
> >>
> >>
> >> WDYT?
> >>
> >> Thanks,
> >> Adel
> >>
>