A Visual Theme consists of a component installed in the /themes folder. The component contains:

  • Theme specific resources (CSS Files, Images, Javascript etc.)
  • Theme specific definitions (configured as seed data)
  • Freemarker templates for theme specific implementations (header, footer, etc.)
  • SCIPIO ERP Templating Toolkit instructions
    • HTML Overrides
    • CSS definitions
  • Theme Sources for modern frontend development (Grunt, Bower, etc.)

Themes are closely tied to the templating toolkit and rely on the toolkit’s macros to style the generated screens. The Community Edition of SCIPIO ERP is bundled with the following themes:

  1. BASE:
    A zurb foundation css based BASE theme
  2. METRO:
    An example theme that inherits and overrides aspects of the BASE theme
  3. FOUNDATION-SHOP:
    A foundation based theme for the SCIPIO ERP webstore. This theme also extends the BASE theme.

Available for purchase and included in the Enterprise Edition is also the BOOTSTRAP_MATERIAL theme – a bootstrap CSS based alternative to the current theme implementations.

Theme Data

Theme specific information are generally stored in the database, which is why a theme definition is always included as seed data. A theme definition will usually look like the following:

<entity-engine-xml>
    <VisualTheme visualThemeId="METRO" visualThemeSetId="BACKOFFICE" description="Metro - Foundation CSS Theme in the style of the Windows Metro design"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_THEME_DATA_RES" resourceValue="component://metro-theme/data/MetroThemeData.xml" sequenceId="01"/>
    
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_NAME" resourceValue="METRO" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_SCREENSHOT" resourceValue="/metro-theme/screenshot.jpg" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_HDR_TMPLT_LOC" resourceValue="component://metro-theme/includes/header.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_MSG_TMPLT_LOC" resourceValue="component://metro-theme/includes/messages.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTR_TMPLT_LOC" resourceValue="component://metro-theme/includes/footer.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_NAV_TMPLT_LOC" resourceValue="component://metro-theme/includes/appbar.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_NAV_OPEN_TMPLT" resourceValue="component://metro-theme/includes/appbarOpen.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_NAV_CLOSE_TMPLT" resourceValue="component://metro-theme/includes/appbarClose.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STL_VAR_LOC" resourceValue="component://metro-theme/includes/themeStyles.groovy" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STL_TMPLT_LOC" resourceValue="component://metro-theme/includes/themeTemplate.ftl" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_SHORTCUT_ICON" resourceValue="/metro-theme/images/favicon.ico" sequenceId="01"/>

    <!-- SCIPIO ERP: The following includes can be used to override specific default pages
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_LOGIN_TMPLT_LOC" resourceValue="component://metro-theme/includes/login.ftl" sequenceId="01"/> // Custom Login Page
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_ERROR_TMPLT_LOC" resourceValue="component://metro-theme/includes/error.ftl" sequenceId="01"/> // Custom Error Page
     -->
    
    <!-- GENERAL -->
    <!-- Styles -->
    <!-- Scripts -->
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_TOP_JAVASCRIPT" resourceValue="/base-theme/bower_components/jquery/dist/jquery.min.js" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_TOP_JAVASCRIPT" resourceValue="/base-theme/bower_components/jquery-migrate/jquery-migrate.min.js" sequenceId="02"/>

    
    <!-- THEME SPECIFIC -->
    <!-- Styles -->
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/base-theme/stylesheets/app.css" sequenceId="01"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/base-theme/bower_components/foundation-datepicker/stylesheets/foundation-datepicker.css" sequenceId="02"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/base-theme/stylesheets/foundation-icons/foundation-icons.css" sequenceId="03"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/base-theme/bower_components/gridster/dist/jquery.gridster.min.css" sequenceId="04"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/base-theme/bower_components/datatables/datatables.min.css" sequenceId="05"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="/metro-theme/css/style.css" sequenceId="06"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_STYLESHEET" resourceValue="//fonts.googleapis.com/css?family=Open+Sans:400,600,300" sequenceId="07"/>
    
    
    <!-- Scripts -->
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/modernizr/modernizr.js" sequenceId="02"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/js/freetile.min.js" sequenceId="04"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/gridster/dist/jquery.gridster.with-extras.min.js" sequenceId="05"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/sass-to-js/js/dist/sass-to-js.min.js" sequenceId="06"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/Chart.js/Chart.min.js" sequenceId="07"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/Snap.svg/dist/snap.svg-min.js" sequenceId="08"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/pizza/dist/js/pizza.min.js" sequenceId="09"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/jquery-ui/jquery-ui.min.js" sequenceId="10"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/foundation/js/foundation.min.js" sequenceId="11"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/foundation/js/foundation/foundation.topbar.js" sequenceId="12"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/foundation/js/foundation/foundation.offcanvas.js" sequenceId="13"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/foundation-datepicker/js/foundation-datepicker.js" sequenceId="14"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/bower_components/datatables/datatables.min.js" sequenceId="15"/>
    <VisualThemeResource visualThemeId="METRO" resourceTypeEnumId="VT_FTPR_JAVASCRIPT" resourceValue="/base-theme/js/app.js" sequenceId="16"/>
</entity-engine-xml>

Each VisualThemeResource is defined by a type (resourceTypeEnumId), which will define when a resource is included. This is particularly useful when you need to define the load order of javascript files. But Resources can also be templates that are later included by our default decorators. This mechanic is also used to inject our theme specific overrides when the html generator is triggered.

themeStyles and themeTemplate.ftl are particularly interesting in this regard. Both files can be found inside the metro-theme/include directory. These optional includes are used by the theme to change the behavior of our templating toolkit. Don’t let the files overwhelm you: they are neatly documented and easy to maintain. So next time you want to change the markup of a specific freemarker macro or need to add additional classes to some of the elements, we can really recommend to do it in these locations.

 

Styles & Scripts

All SCIPIO ERP themes are based on modern HTML frameworks. We adopted the recommended for each of the underlying frameworks, so styles can be modified in multiple ways depending on the framework. Generally speaking, the stylesheet resources are located inside the themes webapp folder. (i.e.: metro/webapp/metro). You always have the option to modify the generated CSS files directly, but we do encourage you to follow the framework’s respective ways for frontend development. Often, this will include the use of other technologies such as SASS or LESS.

Foundation CSS

For further information on the foundation build process. please take a look at the Foundation Installation Guide

SASS setup

To setup system to compile sass files, the following packages/commands are needed (ubuntu/debian/mint):

sudo apt-get install ruby ruby-dev ruby-full nodejs nodejs-dev npm
gem install bundler
gem install compass
gem install foundation
npm install -g bower grunt-cli
bundle install

SASS compile

To start watching for sass changes to auto compile to css, run command:

bundle exec compass watch

Bower update

Run command (TODO, probably incomplete):

bower update

 

Literature