[xwiki-devs] [Proposal] New Best Practices in the App Guide
Hi devs, Following a discussion at http://jira.xwiki.org/browse/XWIKI-12327# I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices Rule: Do not use Skin-specific resources in Extensions/Applications Rationale: If you do, then your Extension/Application will only work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine. Example: This is what happened in apps like in the Forum app which was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a...). WDYT? Anyone disagree? I’d like to clos this topic quickly so that we can close XWIKI-12327. Thanks -Vincent PS: Additional idea (I don’t know if it’s feasible): I wonder if we could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
We expect the extensions to be well integrated into XWiki. This is achieved by using the *current* color theme, the *current* icon set and by limiting the amount of custom styles (use the styles from the *current* skin as much as possible). In order to make the extension consistent with the L&F of XWiki an extension developer will try to use the same icons and images she sees in the XWiki UI (default skin). This is the case with the noavatar image. Best is if the skins use only icons/images defined in the icon set so that extensions use the same images/icons. Thanks, Marius On Tue, Sep 8, 2015 at 12:12 PM, [email protected] <[email protected]> wrote:
Hi devs,
Following a discussion at http://jira.xwiki.org/browse/XWIKI-12327# I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices
Rule: Do not use Skin-specific resources in Extensions/Applications
Rationale: If you do, then your Extension/Application will only work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine.
Example: This is what happened in apps like in the Forum app which was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a...).
WDYT? Anyone disagree? I’d like to clos this topic quickly so that we can close XWIKI-12327.
Thanks -Vincent
PS: Additional idea (I don’t know if it’s feasible): I wonder if we could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 8 Sep 2015 at 11:36:37, Marius Dumitru Florea ([email protected](mailto:[email protected])) wrote:
We expect the extensions to be well integrated into XWiki. This is achieved by using the *current* color theme, the *current* icon set and by limiting the amount of custom styles (use the styles from the *current* skin as much as possible). In order to make the extension consistent with the L&F of XWiki an extension developer will try to use the same icons and images she sees in the XWiki UI (default skin). This is the case with the noavatar image. Best is if the skins use only icons/images defined in the icon set so that extensions use the same images/icons.
Thanks Marius. That’s interesting but I’d put that in the best practice section of the Skin Dev Guide. Icon Set, Color Theme are not supposed to be related to Skins (and they shouldn’t be). So that’s fine. However, if an App uses the styles from a specific Skin, I don’t see how they’ll work when the user uses another skin (and we have several on e.x.o) in his wiki or when the default skin changes (imagine if all extensions need new releases when a new skin is out, that’s a lot of work). What about the best practice I proposed? I couldn’t fully figure out if you agreed or disagreed with it :) If you disagree with it what would be your proposal for XWIKI-12327? Thanks -Vincent
Thanks, Marius
On Tue, Sep 8, 2015 at 12:12 PM, [email protected] wrote:
Hi devs,
Following a discussion at http://jira.xwiki.org/browse/XWIKI-12327# I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices
Rule: Do not use Skin-specific resources in Extensions/Applications
Rationale: If you do, then your Extension/Application will only work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine.
Example: This is what happened in apps like in the Forum app which was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a...).
WDYT? Anyone disagree? I’d like to clos this topic quickly so that we can close XWIKI-12327.
Thanks -Vincent
PS: Additional idea (I don’t know if it’s feasible): I wonder if we could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Tue, Sep 8, 2015 at 12:52 PM, [email protected] <[email protected]> wrote:
On 8 Sep 2015 at 11:36:37, Marius Dumitru Florea ([email protected](mailto:[email protected])) wrote:
We expect the extensions to be well integrated into XWiki. This is achieved by using the *current* color theme, the *current* icon set and by limiting the amount of custom styles (use the styles from the *current* skin as much as possible). In order to make the extension consistent with the L&F of XWiki an extension developer will try to use the same icons and images she sees in the XWiki UI (default skin). This is the case with the noavatar image. Best is if the skins use only icons/images defined in the icon set so that extensions use the same images/icons.
Thanks Marius. That’s interesting but I’d put that in the best practice section of the Skin Dev Guide.
Icon Set, Color Theme are not supposed to be related to Skins (and they shouldn’t be). So that’s fine.
However, if an App uses the styles from a specific Skin, I don’t see how they’ll work when the user uses another skin (and we have several on e.x.o) in his wiki or when the default skin changes (imagine if all extensions need new releases when a new skin is out, that’s a lot of work).
What about the best practice I proposed? I couldn’t fully figure out if you agreed or disagreed with it :)
If the skins use custom icons/images and the extensions are not allowed to use them then they won't be well integrated. There's going to be visual inconsistency between the extensions and the skin. So I'm fine with "Do not use Skin-specific resources in Extensions/Applications" as long as we mention the alternative "use the icon set" and we make sure the skins don't use custom icons/images. For instance, currently we have a bit of inconsistency between the Glyphicons font used by the skin and the FontAwesome font used by the default icon set. A developer might inspect the HTML, see that the Glyphicons font is used in the menu and think that he should use the same. Thanks, Marius
If you disagree with it what would be your proposal for XWIKI-12327?
Thanks -Vincent
Thanks, Marius
On Tue, Sep 8, 2015 at 12:12 PM, [email protected] wrote:
Hi devs,
Following a discussion at http://jira.xwiki.org/browse/XWIKI-12327# I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices
Rule: Do not use Skin-specific resources in Extensions/Applications
Rationale: If you do, then your Extension/Application will only work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine.
Example: This is what happened in apps like in the Forum app which was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a...).
WDYT? Anyone disagree? I’d like to clos this topic quickly so that we can close XWIKI-12327.
Thanks -Vincent
PS: Additional idea (I don’t know if it’s feasible): I wonder if we could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 8 Sep 2015 at 12:03:49, Marius Dumitru Florea ([email protected](mailto:[email protected])) wrote:
On Tue, Sep 8, 2015 at 12:52 PM, [email protected] wrote:
On 8 Sep 2015 at 11:36:37, Marius Dumitru Florea ([email protected](mailto:[email protected])) wrote:
We expect the extensions to be well integrated into XWiki. This is achieved by using the *current* color theme, the *current* icon set and by limiting the amount of custom styles (use the styles from the *current* skin as much as possible). In order to make the extension consistent with the L&F of XWiki an extension developer will try to use the same icons and images she sees in the XWiki UI (default skin). This is the case with the noavatar image. Best is if the skins use only icons/images defined in the icon set so that extensions use the same images/icons.
Thanks Marius. That’s interesting but I’d put that in the best practice section of the Skin Dev Guide.
Icon Set, Color Theme are not supposed to be related to Skins (and they shouldn’t be). So that’s fine.
However, if an App uses the styles from a specific Skin, I don’t see how they’ll work when the user uses another skin (and we have several on e.x.o) in his wiki or when the default skin changes (imagine if all extensions need new releases when a new skin is out, that’s a lot of work).
What about the best practice I proposed? I couldn’t fully figure out if you agreed or disagreed with it :)
If the skins use custom icons/images and the extensions are not allowed to use them then they won't be well integrated. There's going to be visual inconsistency between the extensions and the skin. So I'm fine with "Do not use Skin-specific resources in Extensions/Applications" as long as we mention the alternative "use the icon set" and we make sure the skins don't use custom icons/images. For instance, currently we have a bit of inconsistency between the Glyphicons font used by the skin and the FontAwesome font used by the default icon set. A developer might inspect the HTML, see that the Glyphicons font is used in the menu and think that he should use the same.
FTM I’ve added what’s mentioned at http://jira.xwiki.org/browse/XWIKI-12327?focusedCommentId=87817&page=com.atl... Anyone disagrees or have improved wording suggestions? Thanks -Vincent
Thanks, Marius
If you disagree with it what would be your proposal for XWIKI-12327?
Thanks -Vincent
Thanks, Marius
On Tue, Sep 8, 2015 at 12:12 PM, [email protected] wrote:
Hi devs,
Following a discussion at http://jira.xwiki.org/browse/XWIKI-12327# I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices
Rule: Do not use Skin-specific resources in Extensions/Applications
Rationale: If you do, then your Extension/Application will only work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine.
Example: This is what happened in apps like in the Forum app which was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a...).
WDYT? Anyone disagree? I’d like to clos this topic quickly so that we can close XWIKI-12327.
Thanks -Vincent
PS: Additional idea (I don’t know if it’s feasible): I wonder if we could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
+1 Thanks, Eduard On Tue, Sep 8, 2015 at 3:10 PM, [email protected] <[email protected]> wrote:
On 8 Sep 2015 at 12:03:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
On Tue, Sep 8, 2015 at 12:52 PM, [email protected] wrote:
On 8 Sep 2015 at 11:36:37, Marius Dumitru Florea (
[email protected](mailto:[email protected])) wrote:
We expect the extensions to be well integrated into XWiki. This is achieved by using the *current* color theme, the *current* icon set and by limiting the amount of custom styles (use the styles from the *current* skin as much as possible). In order to make the extension consistent with the L&F of XWiki an extension developer will try to use the same icons and images she sees in the XWiki UI (default skin). This is the case with the noavatar image. Best is if the skins use only icons/images defined in the icon set so that extensions use the same images/icons.
Thanks Marius. That’s interesting but I’d put that in the best
practice section of the Skin Dev Guide.
Icon Set, Color Theme are not supposed to be related to Skins (and
they shouldn’t be). So that’s fine.
However, if an App uses the styles from a specific Skin, I don’t see
how they’ll work when the user uses another skin (and we have several on e.x.o) in his wiki or when the default skin changes (imagine if all extensions need new releases when a new skin is out, that’s a lot of work).
What about the best practice I proposed? I couldn’t fully figure out if you agreed or disagreed with it :)
If the skins use custom icons/images and the extensions are not allowed to use them then they won't be well integrated. There's going to be visual inconsistency between the extensions and the skin. So I'm fine with "Do not use Skin-specific resources in Extensions/Applications" as long as we mention the alternative "use the icon set" and we make sure the skins don't use custom icons/images. For instance, currently we have a bit of inconsistency between the Glyphicons font used by the skin and the FontAwesome font used by the default icon set. A developer might inspect the HTML, see that the Glyphicons font is used in the menu and think that he should use the same.
FTM I’ve added what’s mentioned at http://jira.xwiki.org/browse/XWIKI-12327?focusedCommentId=87817&page=com.atl...
Anyone disagrees or have improved wording suggestions?
Thanks -Vincent
Thanks, Marius
If you disagree with it what would be your proposal for XWIKI-12327?
Thanks -Vincent
Thanks, Marius
On Tue, Sep 8, 2015 at 12:12 PM, [email protected] wrote:
Hi devs,
Following a discussion at http://jira.xwiki.org/browse/XWIKI-12327#
I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices
Rule: Do not use Skin-specific resources in Extensions/Applications
Rationale: If you do, then your Extension/Application will only
work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine.
Example: This is what happened in apps like in the Forum app which
was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a... ).
WDYT? Anyone disagree? I’d like to clos this topic quickly so that
we can close XWIKI-12327.
Thanks -Vincent
PS: Additional idea (I don’t know if it’s feasible): I wonder if we
could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
+1 2015-09-09 12:02 GMT+02:00 Eduard Moraru <[email protected]>:
+1
Thanks, Eduard
On Tue, Sep 8, 2015 at 3:10 PM, [email protected] <[email protected]> wrote:
On 8 Sep 2015 at 12:03:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
On Tue, Sep 8, 2015 at 12:52 PM, [email protected] wrote:
On 8 Sep 2015 at 11:36:37, Marius Dumitru Florea (
[email protected](mailto:[email protected])) wrote:
We expect the extensions to be well integrated into XWiki. This is achieved by using the *current* color theme, the *current* icon set and by limiting the amount of custom styles (use the styles from the *current* skin as much as possible). In order to make the extension consistent with the L&F of XWiki an extension developer will try to use the same icons and images she sees in the XWiki UI (default
skin).
This is the case with the noavatar image. Best is if the skins use only icons/images defined in the icon set so that extensions use the same images/icons.
Thanks Marius. That’s interesting but I’d put that in the best practice section of the Skin Dev Guide.
Icon Set, Color Theme are not supposed to be related to Skins (and they shouldn’t be). So that’s fine.
However, if an App uses the styles from a specific Skin, I don’t see how they’ll work when the user uses another skin (and we have several on e.x.o) in his wiki or when the default skin changes (imagine if all extensions need new releases when a new skin is out, that’s a lot of work).
What about the best practice I proposed? I couldn’t fully figure out if you agreed or disagreed with it :)
If the skins use custom icons/images and the extensions are not allowed to use them then they won't be well integrated. There's going to be visual inconsistency between the extensions and the skin. So I'm fine with "Do not use Skin-specific resources in Extensions/Applications" as long as we mention the alternative "use the icon set" and we make sure the skins don't use custom icons/images. For instance, currently we have a bit of inconsistency between the Glyphicons font used by the skin and the FontAwesome font used by the default icon set. A developer might inspect the HTML, see that the Glyphicons font is used in the menu and think that he should use the same.
FTM I’ve added what’s mentioned at
http://jira.xwiki.org/browse/XWIKI-12327?focusedCommentId=87817&page=com.atl...
Anyone disagrees or have improved wording suggestions?
Thanks -Vincent
Thanks, Marius
If you disagree with it what would be your proposal for XWIKI-12327?
Thanks -Vincent
Thanks, Marius
On Tue, Sep 8, 2015 at 12:12 PM, [email protected] wrote:
Hi devs,
Following a discussion at
http://jira.xwiki.org/browse/XWIKI-12327#
I’d like to propose to add this new best practice in the App Guide, i.e. at http://platform.xwiki.org/xwiki/bin/view/DevGuide/BestPractices
Rule: Do not use Skin-specific resources in
Extensions/Applications
Rationale: If you do, then your Extension/Application will only
work for that Skin. When the default skin in XWiki is modified, your Extension/Application will stop to work fine.
Example: This is what happened in apps like in the Forum app which
was using: getSkinFile(“noavatar.png”) where “noavatar.png” was a Colibri-skin resource only. The Forum app was broken when we moved to Flamingo and the Forum app had to be modified to use getSkinFile("icons/xwiki/noavatar.png”) which is better since it’s a global resource, thus available to all Skins (see
https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a...
).
WDYT? Anyone disagree? I’d like to clos this topic quickly so that
we can close XWIKI-12327.
Thanks -Vincent
PS: Additional idea (I don’t know if it’s feasible): I wonder if
we could even prevent getSkinFile() to return a skin-specific resource if the originating code is not from a resource from this Skin or if the originating code is not located in a Children Skin (i.e. a skin css, skin jss or skin vm). i.e. consider that skin-specific resources have a private access level.
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
participants (4)
-
Eduard Moraru -
Guillaume "Louis-Marie" Delhumeau -
Marius Dumitru Florea -
vincent＠massol.net