3.4.2.4. Best practices

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

How to develop a skin add-on that is compliant with eXo skin?

When developing a skin add-on, you may use some your own components. Using your style is good. However, when you apply the new skin add-on, its theme would not be compatible with the eXo Platform one that is bad. See the below example - dark theme of the new skin add-on is already applied for all, but not applied for the Chat window of eXo Platform.

What is the solution?

It is simple. Reuse the eXo Platform UX component instead of your own UX add-on component. As a result, the theme of Chat add-on will be changed to the new style of your skin add-on.

To get the eXo Platform UX component, see http://exoplatform.github.io/ux-guidelines/Components.html.

How to develop an add-on compliant with eXo skin (login page for instance)?

Never use hard-coded CSS link in JSP file. Instead, use SkinService to get the CSS:


//Use SkinService to get the css

  SkinService skinService = (SkinService) PortalContainer.getCurrentInstance(session.getServletContext())

                          .getComponentInstanceOfType(SkinService.class);

  String loginCssPath = skinService.getSkin("portal/login", "Default").getCSSPath();

//&

<link href="<%=loginCssPath%>" rel="stylesheet" type="text/css"/>

The WEB-INF/gatein-resources.xml related:


<!-- Login Page skins -->

  <portlet-skin>

    <application-name>portal</application-name>

    <portlet-name>login</portlet-name>

    <skin-name>Default</skin-name>

    <css-path>/skin/css/platform/portlets/extensions/login.css</css-path>

  </portlet-skin>

How to develop a gadget compliant with eXo skin?

Simply get the parent CSS (CSS load in Portal):


$(document).ready(function(){



  //Check the parent container of the Iframe

  if(window.top && window.top.location.href != document.location.href) {



    // Get all parent's <link>s

    var linkrels = window.top.document.getElementsByTagName('link');

    // Get the Iframe head

    var iframeHead = document.getElementsByTagName('head').item(0);

    // Loop through parent's links

    for (var i = 0, max = linkrels.length; i < max; i++) {

      // Get parent stylesheets

      if (linkrels[i].rel && linkrels[i].rel == 'stylesheet') {

        // Create new link element and copy all attributes

        var thestyle = document.createElement('link');

        var attrib = linkrels[i].attributes;

        for (var j = 0, attribmax = attrib.length; j < attribmax; j++) {

          thestyle.setAttribute(attrib[j].nodeName, attrib[j].value);

        }



         // add the newly created link element to the head

        iframeHead.appendChild(thestyle);



      }

    }

  }

});

Which tools are recommended for converting .less to .css files?

For developers using Windows, WinLess is an ideal tool. This converts LESS code into static CSS automatically as you save the file and shows reports if any error in the code. Using WinLess, you do not need to rebuild the whole Web UI component packages. You just need to choose output for .css file one time, then modify the .less file and save it. As the result, you will see your changes once refreshing your browser.

Download WinLess and install it. To be compatible with the Less version used in eXo Platform 4.2, the WinLess version should be 1.8.0.
Go to File → Settings, and make sure these options are checked:
- Automatically compile files when saved.
- Show message on successful compile.
Note
Remember to untick the checkbox: Automatically check for less.js updates.
Click Add folder and locate the directory where you put your .less files. WinLess will scan and find all .less files and show them on the list.
Uncheck all files using the top checkbox.
Check the files you modify, or the file importing them. For example, if you want to modify something in variables.less that is imported in Core.less, you only need to check Core.less.
Set the output in case you want to save it elsewhere.
Change the output directory. For the Core.less file, its output directory is $PLATFORM_TOMCAT_HOME/webapps/eXoSkin/skin/css/core.css.
Open variables.less and make a few changes, then save it. The WinLESS will notify you when the file has been successfully compiled into .css or if any error in the code. By using this way, you can check the .css output directly, without waiting for the code to complete its compilation.
Refresh the web browsers to see your changes.

Note

If you are using MAC or Linux, you can use Koala.

Mapping between .less and .css files

Here is the list of .less files corresponding to the compiled .css files in eXo Platform.

Projects	Input Path Less	Output Path Css
Platform UI	`platform-ui-skin/src/main/webapp/skin/less/Core.less`	`webapps/eXoSkin/skin/css/Core.css`
Calendar	`platform-ui-skin/src/main/webapp/skin/less/calendar/calendar.less`	`webapps/eXoSkin/skin/css/calendar/calendar.css`
Commons	`platform-ui-skin/src/main/webapp/skin/less/commons/skin/commons.less`	`webapps/eXoSkin/skin/css/commons/skin/commons.css`
ECMS	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/administration/ecms-administration.less`	`webapps/eXoSkin/skin/css/ecms/portlets/administration/ecms-administration.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/explorer/ecms-explorer.less`	`webapps/eXoSkin/skin/css/ecms/portlets/explorer/ecms-explorer.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/fastcontentcreator/fast-content-creator.less`	`webapps/eXoSkin/skin/css/ecms/portlets/fastcontentcreator/fast-content-creator.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/presentation/ecms-presentation-categorynavigationportlet.less`	`webapps/eXoSkin/skin/css/ecms/portlets/presentation/ecms-presentation-categorynavigationportlet.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/presentation/ecms-presentation-contentlistviewerportlet.less`	`webapps/eXoSkin/skin/css/ecms/portlets/presentation/ecms-presentation-contentlistviewerportlet.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/presentation/ecms-presentation-singlecontentviewer.less`	`webapps/eXoSkin/skin/css/ecms/portlets/presentation/ecms-presentation-singlecontentviewer.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/portlets/search/ecms-search.less`	`webapps/eXoSkin/skin/css/ecms/portlets/search/ecms-search.css`
	`platform-ui-skin/src/main/webapp/skin/less/ecms/skin/ecms-resources-wcmskin.less`	`webapps/eXoSkin/skin/css/ecms/skin/ecms-resources-wcmskin.css`
Forum	`platform-ui-skin/src/main/webapp/skin/less/forum/portlets/answer/faq.less`	`webapps/eXoSkin/skin/css/forum/portlets/answer/faq.css`
	`platform-ui-skin/src/main/webapp/skin/less/forum/portlets/forum/forum.less`	`webapps/eXoSkin/skin/css/forum/portlets/forum/forum.css`
	`platform-ui-skin/src/main/webapp/skin/less/forum/portlets/poll/pollPortlet.less`	`webapps/eXoSkin/skin/css/forum/portlets/poll/pollPortlet.css`
	`platform-ui-skin/src/main/webapp/skin/less/forum/skin/forum-resources.less`	`webapps/eXoSkin/skin/css/forum/skin/forum-resources.css`
Integration	`platform-ui-skin/src/main/webapp/skin/less/integration/skin/quicksearchpage.less`	`webapps/eXoSkin/skin/css/integration/skin/quicksearchpage.css`
	`platform-ui-skin/src/main/webapp/skin/less/integration/skin/searchAdmin.less`	`webapps/eXoSkin/skin/css/integration/skin/searchAdmin.css`
	`platform-ui-skin/src/main/webapp/skin/less/integration/skin/searchpage.less`	`webapps/eXoSkin/skin/css/integration/skin/searchpage.css`
Platform	`platform-ui-skin/src/main/webapp/skin/less/platform/skin/platform.less`	`webapps/eXoSkin/skin/css/platform/skin/platform.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/branding/branding.less`	`webapps/eXoSkin/skin/css/platform/portlets/branding/branding.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/extensions/login.less`	`webapps/eXoSkin/skin/css/platform/portlets/extensions/login.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/extensions/welcome-screens.less`	`webapps/eXoSkin/skin/css/platform/portlets/extensions/welcome-screens.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/homepage/calendar.less` (Calendar application at the right navigation)	`webapps/eXoSkin/skin/css/platform/portlets/homepage/calendar.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/homepage/gettingstarted.less` (Getting Started application at the right navigation)	`webapps/eXoSkin/skin/css/platform/portlets/homepage/gettingstarted.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/homepage/invitations.less` (Invitations application at the right navigation)	`webapps/eXoSkin/skin/css/platform/portlets/homepage/invitations.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/homepage/suggestions.less` (Suggestions application at the right navigation)	`webapps/eXoSkin/skin/css/platform/portlets/homepage/suggestions.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/homepage/whoisonline.less` (Who's Online application at the right navigation)	`webapps/eXoSkin/skin/css/platform/portlets/homepage/whoisonline.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/notification/notificationsAdmin.less`	`webapps/eXoSkin/skin/css/platform/portlets/notification/notificationsAdmin.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UIBreadCrumbsNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UIBreadCrumbsNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UICompanyNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UICompanyNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UIGroupsNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UIGroupsNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UIHelpPlatformToolbarPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UIHelpPlatformToolbarPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UISearchPlatformToolbarPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UISearchPlatformToolbarPortlet/Style.css`
	`platform-ui/platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UISpaceNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UISpaceNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/platformNavigation/UIUserNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/platformNavigation/UIUserNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/samples/acme-intranet/SpaceSummaryInfoPortlet.less`	`webapps/eXoSkin/skin/css/platform/portlets/samples/acme-intranet/SpaceSummaryInfoPortlet.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/samples/acme-website/Style.less`	`webapps/eXoSkin/skin/css/platform/portlets/samples/acme-website/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/platform/portlets/welcome-screens/termsandconditions.less`	`webapps/eXoSkin/skin/css/platform/portlets/welcome-screens/termsandconditions.css`
	`webapp/skin/less/platform/portlets/welcome-screens/unlockTrial.less`	`webapps/eXoSkin/skin/css/platform/portlets/welcome-screens/unlockTrial.css`
Portlets	`platform-ui-skin/src/main/webapp/skin/less/Portlets/SiteNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/Portlets/SiteNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/Portlets/UIAccountPortlet/Style.less` (Account portlet)	`webapps/eXoSkin/skin/css/Portlets/UIAccountPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/Portlets/UIApplicationRegistryPortlet/Style.less` (Registry portlet)	`webapps/eXoSkin/skin/css/Portlets/UIApplicationRegistryPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/Portlets/UIOrganizationPortlet/Style.less` (Organization portlet)	`webapps/eXoSkin/skin/css/Portlets/UIOrganizationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/Portlets/UITabbedDashboardPortlet/Style.less` (Dashboard portlet)	`webapps/eXoSkin/skin/css/Portlets/UITabbedDashboardPortlet/Style.css`
Social	`platform-ui-skin/src/main/webapp/skin/less/social/juzu-portlet/notification.less`	`webapps/eXoSkin/skin/css/social/juzu-portlet/notification.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiAllPeoplePortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiAllPeoplePortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiAllSpacesPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiAllSpacesPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiBannerPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiBannerPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiConnectionsNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiConnectionsNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiConnectionsPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiConnectionsPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiFooterPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiFooterPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiInvitationSpacesPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiInvitationSpacesPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiInvitationsPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiInvitationsPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiMembersPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiMembersPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiMyConnectionsNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiMyConnectionsNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiMySpacesPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiMySpacesPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiPendingSpacesPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiPendingSpacesPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiPeoplePortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiPeoplePortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiPeopleToolbarPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiPeopleToolbarPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiProfileNavigatonPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiProfileNavigatonPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiProfilePortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiProfilePortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiPublicSpacesPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiPublicSpacesPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiRequestsPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiRequestsPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSocialDemoHomePagePortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSocialDemoHomePagePortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSocialDemoNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSocialDemoNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSocialExtensionHomePagePortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSocialExtensionHomePagePortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSocialExtensionLogoPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSocialExtensionLogoPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSocialNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSocialNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSpaceAccessPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSpaceAccessPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSpaceActivityStreamPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSpaceActivityStreamPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSpaceMenuPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSpaceMenuPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSpaceNavigationPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSpaceNavigationPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSpaceSettingPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSpaceSettingPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiSpaceToolbarPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiSpaceToolbarPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiUserActivityStreamPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiUserActivityStreamPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/portlets/uiWarningPortlet/Style.less`	`webapps/eXoSkin/skin/css/social/portlets/uiWarningPortlet/Style.css`
	`platform-ui-skin/src/main/webapp/skin/less/social/skin/social.less`	`webapps/eXoSkin/skin/css/social/skin/social.css`
Wiki	`platform-ui-skin/src/main/webapp/skin/less/wiki/wiki.less`	`webapps/eXoSkin/skin/css/wiki/wiki.css`