ftw.theming 1.0.1

Inspecting the SCSS registry

The @@theming-resources (on any navigation root) lists all resources.

Resource slots

The registry allows to register resources to a list of fix slots. Theese are the available slots, sorted by inclusion order:

• top

• variables

• mixins

• ftw.theming

• addon

• theme

• policy

• bottom

Adding resources

Adding SCSS resources is done in the ZCML of a package. The SCSS should always go into the same package where the styled templates are.

<configure
    xmlns:theme="http://namespaces.zope.org/ftw.theming"
    xmlns:zcml="http://namespaces.zope.org/zcml"
    i18n_domain="ftw.tabbedview">

    <configure zcml:condition="installed ftw.theming">
      <include package="ftw.theming" />

      <theme:scss
          file="resources/tabbed.scss"
          slot="addon"
          profile="ftw.tabbedview:default"
          />
    </configure>

</configure>

<configure
    xmlns:theme="http://namespaces.zope.org/ftw.theming"
    xmlns:zcml="http://namespaces.zope.org/zcml"
    i18n_domain="plonetheme.fancy">

    <include package="ftw.theming" />

    <theme:resources
        slot="theme"
        profile="plonetheme.fancy:default"
        layer="plonetheme.fancy.interfaces.IFancyTheme">

        <theme:scss file="resources/foo.scss" />
        <theme:scss file="resources/bar.scss" />

    </theme:resources>

</configure>

Resource Ordering

The SCSS resources are ordered when retrieved from the registry, so that the order is as consistent as possible.

Ordering priority:

1. the resource’s slot (see the slot section below) 1. the before and after options (topological graph sorting), within each slot. 1. the ZCML load order of the resources

Be aware that the ZCML load order is usally random.

Resource factories for dynamic resources

A resource factory is a callable (accepting context and request) which returns a DynamicSCSSResource object. Since the callable instantiates the resource, it’s content can be created dynamically.

<configure
    xmlns:theme="http://namespaces.zope.org/ftw.theming"
    xmlns:zcml="http://namespaces.zope.org/zcml"
    i18n_domain="plonetheme.fancy">

    <include package="ftw.theming" />

    <theme:scss_factory factory=".dynamic_resource_factory" />

</configure>

from ftw.theming.interfaces import ISCSSResourceFactory
from ftw.theming.resource import DynamicSCSSResource
from zope.interface import provider

@provider(ISCSSResourceFactory)
def dynamic_resource_factory(context, request):
    return DynamicSCSSResource('dynamic.scss', slot='addon', source='$color: blue;',
                               cachekey='1')

When generating the SCSS is expensive in time, you should subclass the DynamicSCSSResource class and implement custom get_source and get_cachekey methods. The get_cachekey should be very lightweight and cheap: it is called on every pageview. It should return any string and only change the return value when the get_source result will change.

from Products.CMFCore.utils import getToolByName
from ftw.theming.interfaces import ISCSSResourceFactory
from ftw.theming.resource import DynamicSCSSResource
from zope.annotation import IAnnotations
from zope.interface import provider


class CustomSCSSResource(DynamicSCSSResource):

      def get_source(self, context, request):
          return 'body { background-color: $primary-color; }'

      def get_cachekey(self, context, request):
          portal = getToolByName(context, 'portal_url').getPortalObject()
          config = IAnnotations(portal).get('my-custom-config', {})
          return config.get('last-change-timestamp', '1')

@provider(ISCSSResourceFactory)
def dynamic_resource_factory(context, request):
    return CustomSCSSResource('my.package:custom.scss', slot='addon')

Declare icon for portal types

Portal type icons are declared in the scss file of the addon package. It is possible to support multiple icon sets by declaring icons for each iconset:

@include portal-type-font-awesome-icon(repository-folder, leaf);
@include portal-type-icon(repository-folder, "\e616", customicons);

Using those mixins does not generate any CSS yet, nor does it introduce dependency to those iconset. It simply stores this information in a list to be processed later.

Switching iconset

A theme or policy package may change the iconset. The standard iconset is font-awesome. Changing the iconset should be done in an SCSS file in the variables slot.

$standard-iconset: customicons;

Custom iconsets

The default iconset is font-awesome, which is automatically loaded and the necessary CSS is generated when the $standard-iconset variable is font-awesome.

For having custom iconsets an SCSS file must be registered in the bottom slot. This is usually done by a theme or policy package.

The SCSS file should apply the necessary CSS only when the $standard-iconset is set to this iconset:

@if $standard-iconset == customicons {

  @font-face {
    font-family: 'customicons';
    src:url('#{$portal-url}/++theme++foo/fonts/customicons.eot?-fa99j8');
    src:url('#{$portal-url}/++theme++foo/fonts/customicons.eot?#iefix-fa99j8') format('embedded-opentype'),
    url('#{$portal-url}/++theme++foo/fonts/customicons.woff?-fa99j8') format('woff'),
    url('#{$portal-url}/++theme++foo/fonts/customicons.ttf?-fa99j8') format('truetype'),
    url('#{$portal-url}/++theme++foo/fonts/customicons.svg?-fa99j8#opengever') format('svg');
    font-weight: normal;
    font-style: normal;
  }

  .icons-on [class^="contenttype-"],
  .icons-on [class*=" contenttype-"] {
    &:before {
      font-family: 'customicons';
      content: "x";
      text-align:center;
      position: absolute;
    }
  }

  @each $type, $value in get-portal-type-icons-for-iconset(font-awesome) {
    body.icons-on .contenttype-#{$type} {
      &:before {
        content: $value;
      }
    }
  }
}

1.0.1 (2015-10-26)

• Remove duplicate icon in search results for files. [jone]

1.0.0 (2015-09-30)

• Initial implementation [jone]