Theming ISPconfig

Discussion in 'Tips/Tricks/Mods' started by rubenmdh, May 10, 2017.

  1. rubenmdh

    rubenmdh New Member

    I am using the latest version of ISPconfig and It is great so far, I like way more this theme than the one was before, but I'd like to mod it.

    Has the structure changed from the old theme to this one? (I think so but I need to reassure myself)
    And, could you give me some tips on where can I modify the theme itself.

  2. vk3heg

    vk3heg Member

    I would love to see a "Dark" theme. The current one is just to white. There used to be a dark theme with the previous versions, but it doesn't work 100% with the 3.1x...
  3. Farsus

    Farsus Member

  4. teves

    teves Member


    I have had a closer look on ISPConfig theming in the last few days, and would like to share my findings:

    1. Themes can be found in the interface/web/themes directory; in the standard installation there ist only 'default'. The name of the folder here defines the name of the theme.
    2. Each theme consists of two folders, assets and templates.
    3. The files in templates are defining the skeleton of the theme; they consist of a mixture of HTML and parts of the templating engine used in ISPConfig, vlibTemplate (you can find the engine in interface/lib/classes/
      Roughly speaking, these files define the HTML structure of the principal elements like main- and side navigation, login page etc.
    4. In assets, there are all the additional files needed by the theme, sorted into the folders fonts, images, javascripts and stylesheets.
    5. In fonts there are, obviously, fonts. More accurate: there are two fonts, glyphicons-halflings-regular and ispconfig. glyphicons-halflings-regular seems to be unused. ispconfig does mainly contain the symbols used in the GUI, e.g. in the main navigation (home, help, client...)
      I do personally deplore this design decision, for I am a developer of ISPConfig plugins, and there is no way for me to insert my own plugin icons into the main menu without changing the font/theme.
    6. In images there are some, well, images. Some of them seem to be obsolete: plus.png and arrow.png have zero bytes and both are not used anywhere. The logo is, apart from here, also saved in the database (in sys_ini); I do not know why it is stored in two different places.
    7. javascripts holds all the jQuery dependent plugin files, like bootstrap, pushy etc.
    8. stylesheets is one of the more interesting folders when it comes to developing your own theme. To begin with, this folder contains the CSS needed by the jQuery plugins , like select2, pushy, etc.
      Then, there are ISPConfig style files: fonts.css, ispconfig.css, login.css and responsive.css. These files do mainly define the form of the named parts; the colors though are defined elsewhere.
    9. This would be in the stylesheets/themes directory. Inside stylesheets/themes there are the dark and default sub-directories. dark seems to be completely unused; all of the theme color definitions are inside default.
    10. In default there is the theme.min.css file (theme.css can be read more easily, but be aware that only theme.min.css is actually used by ISPConfig).
      In theme.min.css all the color defninitions take place.
    11. In stylesheets and stylesheets/themes/default there are also some [filename].sass files.
      What are these?
      SASS is an extension to the CSS language. It makes it more easy to structure you css and to do changes afterwards. Basically, you make definitions in SASS files and then use a tool to sort-of compile your SASS files to plain CSS. Learn more here.
      So, to change the colors in the theme, you would have to:
      1. edit stylesheets/themes/default/colors.sass.
      2. compile the stylesheets/themes/default/theme.sass file with SASS (There are Windows tools for that also!)
      3. replace the theme.min.css file by the newly generated one
    While the usage of SASS basically is a great idea, I would have personally preferred LESS. SASS generally seems to be the more powerful software, but ISPConfig does not use the 'more powerful' features. Also, SASS relies on ruby, while LESS works with a javaScript plugin. That means, with LESS you can develop a sort of 'theme designer' where you can view the changes (nearly) live.

    I have developed a small tool to edit the theme colors. For this purpose I translated the default theme to LESS. Works pretty well :)

    While fidling with different themes I found one strange line in the code of interface/web/login/index.php:
    // check if the user theme is valid
    if ($_SESSION['s']['user']['theme'] != 'default') {
    $tmp_path ISPC_THEMES_PATH "/" $_SESSION['s']['user']['theme'];
                                if (!@
    is_dir($tmp_path) || !@file_exists($tmp_path "/ispconfig_version") || trim(file_get_contents($tmp_path "/ispconfig_version")) != ISPC_APP_VERSION) {
                                if (!@
    is_dir($tmp_path) ) {
    // fall back to default theme if this one is not compatible with current ispc version

    $_SESSION['s']['user']['theme'] = 'default';
    $_SESSION['s']['theme'] = 'default';
    $_SESSION['show_error_msg'] = $app->lng('theme_not_compatible');
    This test is done whenever the chosen theme is different from 'default'. But there is no ispconfig_version file in the default theme. So if you copy the default theme, give it a new folder name (in interface/web/themes) and change it to your desire, it will never be displayed, because ISPConfig cannot find the ispconfig_version file.
    @developers: Can it be this test is a leftover from earlier ISPConfig versions? Can it be removed in the next minor release?

    Best regards, Tom
    Ajayi David likes this.
  5. till

    till Super Moderator Staff Member ISPConfig Developer

    The default theme does not need that file as it is developed together with ISPConfig and therefore it is always compatible with the currently installed ISPConfig version and that's the reason why it does not contain such a file. If you create a custom theme, then you as the theme author have to add this file. It has to contain the version number of the ISPConfig release that your custom theme is compatible with. This has been made to ensure that only themes that have been tested with a new release get's used as we had a lot of problem here before we added that check that poeple reported issues in their custom themes as ispconfig bugs simply because they did not make their themes compatible with the installed ISPConfig version. So this check is intended and will not be removed.
  6. teves

    teves Member

    Ok I see.
    So I have to put e.g. '3.1.6' into the ispconfig_version file. But that would mean you had to update themes with every minor ISPConfig update. To my mind this would be rather annoying, don't you think?
  7. till

    till Super Moderator Staff Member ISPConfig Developer

    I guess we can this to a major version number check aor maybe even a range of versions. But this will bring us back some of the problems as ISPConfig allows rather detailed theming, e.g. a theme can override each single html template file of any module. Some theme authors did that and when we e.g. added a checkbox in a form, then this was missing in that theme, the theme users were not aware of that and then started complaining here why the new checkbox was not there in their ispconfig version. And that's why we started to force themes to identify themselves as compatible with the installed ISPConfig version and in case that a theme does not do it, we will fall back to the default theme.
  8. pannet1

    pannet1 Member


    i have created a new theme called fluid. the change from the default theme and this is just deletion of one line from the ispconfig.css file. ispconfig default theme though technically uses a fluid layout, it is not taking advantage of the full width of the screen real estate. this is because the wrapper class is capping the max-width to 1###px.

    so if we remove that .. we get a full real estate. also the select boxes could not accommodate all the values and it becomes truncated, so we need to guess the name most of the time. this change also allows us to see the full values without truncation.

    Please press the Like button below, if you like my work :)
    ahrasis likes this.
  9. pannet1

    pannet1 Member

    Thanks ahrasis for the like, Now I got super ninja powers to upload images and have signature.
    Jesse Norell likes this.
  10. pannet1

    pannet1 Member

Share This Page