Versions Compared

Old Version 9

changes.mady.by.user Antoine Snyers (Atmire)

Saved on

compared with

New Version 10

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add build / enable instructions into this page (in case they are overlooked in Install/Upgrade instructions). Other minor cleanup

...

A responsive website is a website that rearranges its content to fit in different screen sizes. The main focus is to provide a better overall user experience whether you're browsing on a mobile phone, a tablet or desktop computer. As opposed to using a separate mobile theme, there's only one version of the website that will work everywhere. A simply way to find out what the differences are between a narrow screen and a larger screen in Mirage 2, go to any webpage and resize the browser window. You will notice the sidebar is only shown when the window is large enough, otherwise a menu button is displayed to get to the sidebar options. The theme provides a distinct look for each of the 3 different categories of screen sizes: mobile, tablet and desktop.

The build process and enabling Mirage 2

The modern web technologies that power Mirage 2 include a precompiler (compassCompass), a package manager (bowerBower) and a task runner (gruntGrunt). These tools can only be installed when some prerequisites are present on the system. DSpace's maven Maven build process is capable of making a temporary installation of these dependencies just so the theme can be built. However the overall build time will be significantly shortened if these dependencies are installed on the system. More information on the prerequisites.

By default, DSpace does not build the Mirage 2 theme (as it lengthens the normal build process).  However, you can easily tell DSpace to build Mirage 2 by running:

Code Block
mvn package -Dmirage2.on=true

If you wish to speed up the Mirage 2 build process, you can do so by pre-installing all of the Mirage 2 dependencies on your system (by default they will be downloaded each time you rebuild Mirage 2).  This will significantly shorten the build process for Mirage 2.  More information on installing these prerequisites can be found in the Installation Instructions for Mirage 2.  Once these prerequisites have been installed on your local server, you can then build Mirage 2 more rapidly by running:

Code Block
# WARNING: This command will only work if you've manually installed *all* the prerequisites for Mirage 2
mvn package -Dmirage2.on=true -Dmirage2.deps.included=false

After building Mirage 2, you can install it into your DSpace installation by simply re-running Ant:

Code Block
ant update

To enable Mirage 2, add the following to the <themes> section of your xmlui.xconf, replacing the currently active theme:

Code Block
<theme name="Mirage 2" regex=".*" path="Mirage2/" />

Finally, restart your Tomcat or servlet container, and you should see the Mirage 2 theme.

Configuration options

Mirage 2 adds two configuration options to dspace.cfg that affect the rendering of bitstream labels on item pages:

...

Warning
titleDo not attempt the following

Do not attempt to manage local customizations to Mirage 2 in:

  • src[dspace-source]/dspace/modules/xmlui/src/main/webapp/themes
    • This is where you would put standard XMLUI Themes or customizations. However, because of the Mirage 2 build process, this won't work.
  • src[dspace-source]/dspace-xmlui-mirage2
    • This is the place where the community, committers and contributors manage the STANDARD version of Mirage 2. You could change files there if your intention is to create a contribution that would benefit everyone. But in this case, we are not talking about a local customization.
Tip
titleRecommended approach

Manage your local Mirage 2 customizations or derived themes in:

src[dspace-source]/dspace/modules/xmlui-mirage2

Managing your local customizations in this folder comes with the advantage that you ONLY need to keep files you have changed, compared to the standard Mirage 2 folder. To get you started, the contributors have added a _styles.scss file where you can make local scss customizations:

dspace/modules/xmlui-mirage2/src/main/webapp/themes/Mirage2/styles

...

The style sheet of Mirage 2 is written in sass and relies on the bootstrap framework. A big advantages of this is the ease of changing the color scheme. By default Mirage 2 has the colors that are familiar from the classic Mirage theme, but another color scheme with only the standard bootstrap colors is also ready and available. In fact this color scheme can be activated by building DSpace using one extra maven profile, mirage2_bootstrap_color_scheme.

The classic mirage theme is a customization of the bootstrap theme. Thanks to the sass variables, a complete color scheme can be conceived by modifying one or two variables. These variables are set in the theme's /styles/classic_mirage_color_scheme/_bootstrap_variables.scss. Copy this file into [dspace-source]/dspace/modules/xmlui-mirage2/src/main/webapp./themes/Mirage2  Mirage2  and see what happens when you change $brand-primary. More detailed information on how to customize this file can be found in the Mirage 2 readme.

...

As mentioned in the previous section, make sure you manage this file and any changes you make to it in [dspace-source]/dspace/modules modules (e.g. dspace [dspace-source]/dspace/modules/xmlui-mirage2/src/main/webapp/themes/Mirage2). It is not recommended to update the officially distributed bower.json file directly in [dspace-source]/dspace-xmlui-mirage2

Additional Developer documentation

...