Developer Resources#

User Documentation#

Themes#

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:

AURORA: The default theme of the administration interface since 4.0. Aurora is written without a CSS framework and ships a light and a dark scheme. The scheme comes from the auroraScheme cookie first, then from the reader’s AURORA_SCHEME user preference; an empty value follows the operating system. The scheme is written on the <html> element as data-theme.
BASE: A zurb foundation css based BASE theme
METRO: An example theme that inherits and overrides aspects of the BASE theme
BULMATHEME: A Bulma CSS based theme
FOUNDATION‑SHOP: A foundation based theme for the SCIPIO ERP webstore. This theme also extends the BASE theme.
IGNITE_ADMIN and IGNITE_SHOP: Bootstrap v4 based themes for the administration interface and for the webstore. Both ship in the source tree.

A theme is a component of its own, and it carries a scipio-theme.xml descriptor rather than the scipio-component.xml an application carries. Every directory under themes/ is loaded automatically.

See the Aurora theme page for its design tokens, file layout, and how the light and dark scheme switch works.

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:

text
<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):

text
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:

text
bundle exec compass watch

Bower update#

Run command (TODO, probably incomplete):

text
bower update

Themes