otuoma/DSpace 6 - Customize Mirage 2 theme.ipynb

## DSpace 6 - Customize Mirage 2 theme.ipynb
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# DSpace with Mirage 2 theme : Basic Customization \n",
    "\n",
    "For this document to make sense, you need to have a basic understanding of HTML, CSS and XML.\n",
    "\n",
    "DSpace customization can be done at three levels:\n",
    "1. **Style Tier** - Uses CSS and HTML to style the theme\n",
    "2. **Theme Tier** - Uses XSLT, HTML and CSS to do more complex customization\n",
    "3. **Aspect Tier** - Uses the Cocoon framework and Java to customize DSpace.\n",
    "\n",
    "In this guide, we will concentrate on the **style tier**\n",
    "\n",
    "Dspace UI customization is all about knowing which files to modify. This can be achieved by editing several files.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.  Remove \"DSpace\" from Pages\n",
    "\n",
    "An example of where \"DSpace\" occures is in the title of the home page.\n",
    "To make these changes, we need to carefully modify **webapps/xmlui/i18n/messages.xml** file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano webapps/xmlui/i18n/messages.xml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Find all occurances of the word \"DSpace\" in the file and replace it with your prefered text. For instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<message key=\"xmlui.general.dspace_home\">DSpace Home</message>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Can be changed to"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<message key=\"xmlui.general.dspace_home\">Repository Home</message>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: Only change what is inbetween the XML tags. Any accidental or intentional modification of the XML tags will break the system."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Modify Home Page Message\n",
    "\n",
    "The home page message can be modified in the file **[config/news-xmlui.xml]**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano config/news-xmlui.xml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The file has the contents shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n",
    "<document xmlns=\"http://di.tamu.edu/DRI/1.0/\" xmlns:i18n=\"http://apache.org/cocoon/i18n/2.1\" version=\"1.1\">\n",
    "<body>\n",
    "<div id=\"file.news.div.news\" n=\"news\" rend=\"primary\">\n",
    "<head>DSpace Repository</head>\n",
    "<p>\n",
    "DSpace is a digital service that collects, preserves, and distributes digital material. \n",
    "Repositories are important tools for preserving an orga$\n",
    "</div>\n",
    "</body>\n",
    "<options/>\n",
    "<meta>\n",
    "<userMeta/>\n",
    "<pageMeta/>\n",
    "<repositoryMeta/>\n",
    "</meta>\n",
    "</document>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Modify Footer Contents\n",
    "\n",
    "The content of the footer is found in the file **webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Modify branding: Logo, colors and styling\n",
    "\n",
    "Mirage 2 theme is built with bootstrap UI framework.\n",
    "\n",
    "### The logo\n",
    "\n",
    "If you inspect the source code on the home page, you will notice that the logo is located at [webapps/xmlui/themes/Mirage2/images/DSpace-logo-line.svg]\n",
    "\n",
    "To replace this logo with our own, place your logo in the same directory and modify the file [webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Locate this section below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<a href=\"{$context-path}/\" class=\"navbar-brand\">\n",
    "    <img src=\"{$theme-path}images/DSpace-logo-line.svg\" />\n",
    "</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Modify the image name to refer to the image name of your logo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: You need to use an FTP client (eg WinSCP or filezilla) to copy the image from your laptop to the server."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Styling and colors\n",
    "Changing the look and feel of dspace is easy if you know CSS (Cascading Style Sheets). \n",
    "\n",
    "This can all be done from the file  [webapps/xmlui/themes/Mirage2/styles/main.css]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano webapps/xmlui/themes/Mirage2/styles/main.css"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NOTE: Learn to copy from others. If there's a dspace repository that you like how it has been customized, it is no offense looking at the HTML source-code and styling to get ideas on how it has been customized."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Customizing Input Forms\n",
    "\n",
    "Sometimes it is neccessary to customize input forms to add features, reorder lements or entirely remove them.\n",
    "\n",
    "In this example, we will add Swahili language to one of the language options in the metadata workflow.\n",
    "\n",
    "Configuration for input forms can be found in [config/input-forms.xml].\n",
    "\n",
    "Locate the line with the XML code below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<value-pairs value-pairs-name=\"common_iso_languages\" dc-term=\"language_iso\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then add the XML code below as its child element. It is also possible that you can replace a language that you're almost sure you will never use with the new one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<pair>\n",
    "    <displayed-value>Swahili</displayed-value>\n",
    "    <stored-value>sw</stored-value>\n",
    "</pair>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Save the file and close the file.\n",
    "\n",
    "When you go to submit a new document to dspace, you will now be able to see Swahili as one of the available languages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Adding Static Pages\n",
    "\n",
    "Additional static pages (including \\*.html) files can be placed in *webapps/xmlui/static* directory.\n",
    "To demonstrate this, create a page with the following commands in succession:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nano webapps/xmlui/static/my-page.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then paste the HTML code below, save and close."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "<!DOCTYPE html>\n",
    "<html lang=\"en\">\n",
    "<head>\n",
    "    <meta charset=\"UTF-8\">\n",
    "    <title>My DSPace Page</title>\n",
    "    <style type=\"text/css\">\n",
    "\tbody{\n",
    "\t    background: #eee;\n",
    "\t}\n",
    "    </style>\n",
    "</head>\n",
    "<body>\n",
    "<h1>My Static DSpace Page</h1>\n",
    "<table border=\"1\">\n",
    "    <tr>\n",
    "        <td>blue</td><td>blue</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <td>red</td><td>blue</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <td>black</td><td>blue</td>\n",
    "    </tr>\n",
    "</table>\n",
    "</body>\n",
    "</html>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "External style sheets, javascript and images can be refenced with paths relative to this folder"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PRO-TIP : Search Text Manually\n",
    "\n",
    "If there's a piece of text on a dspace page that you need to modify but don't know which file to edit, run the code below to help you find it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "grep -iR \"text you are searching for\" ./"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will list all files that contain the text in quotes by searching all files in the current directory and all its subdirectories ignoring case sensitivity."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Bash",
   "language": "bash",
   "name": "bash"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
	{
	"cells": [
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"# DSpace with Mirage 2 theme : Basic Customization \n",
	"\n",
	"For this document to make sense, you need to have a basic understanding of HTML, CSS and XML.\n",
	"\n",
	"DSpace customization can be done at three levels:\n",
	"1. Style Tier - Uses CSS and HTML to style the theme\n",
	"2. Theme Tier - Uses XSLT, HTML and CSS to do more complex customization\n",
	"3. Aspect Tier - Uses the Cocoon framework and Java to customize DSpace.\n",
	"\n",
	"In this guide, we will concentrate on the style tier\n",
	"\n",
	"Dspace UI customization is all about knowing which files to modify. This can be achieved by editing several files.\n"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 1. Remove \"DSpace\" from Pages\n",
	"\n",
	"An example of where \"DSpace\" occures is in the title of the home page.\n",
	"To make these changes, we need to carefully modify webapps/xmlui/i18n/messages.xml file."
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"nano webapps/xmlui/i18n/messages.xml"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Find all occurances of the word \"DSpace\" in the file and replace it with your prefered text. For instance:"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<message key=\"xmlui.general.dspace_home\">DSpace Home</message>"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Can be changed to"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<message key=\"xmlui.general.dspace_home\">Repository Home</message>"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"NOTE: Only change what is inbetween the XML tags. Any accidental or intentional modification of the XML tags will break the system."
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 2. Modify Home Page Message\n",
	"\n",
	"The home page message can be modified in the file [config/news-xmlui.xml]"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"nano config/news-xmlui.xml"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"The file has the contents shown below."
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n",
	"<document xmlns=\"http://di.tamu.edu/DRI/1.0/\" xmlns:i18n=\"http://apache.org/cocoon/i18n/2.1\" version=\"1.1\">\n",
	"<body>\n",
	"<div id=\"file.news.div.news\" n=\"news\" rend=\"primary\">\n",
	"<head>DSpace Repository</head>\n",
	"<p>\n",
	"DSpace is a digital service that collects, preserves, and distributes digital material. \n",
	"Repositories are important tools for preserving an orga$\n",
	"</div>\n",
	"</body>\n",
	"<options/>\n",
	"<meta>\n",
	"<userMeta/>\n",
	"<pageMeta/>\n",
	"<repositoryMeta/>\n",
	"</meta>\n",
	"</document>"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 3. Modify Footer Contents\n",
	"\n",
	"The content of the footer is found in the file webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"nano webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 4. Modify branding: Logo, colors and styling\n",
	"\n",
	"Mirage 2 theme is built with bootstrap UI framework.\n",
	"\n",
	"### The logo\n",
	"\n",
	"If you inspect the source code on the home page, you will notice that the logo is located at [webapps/xmlui/themes/Mirage2/images/DSpace-logo-line.svg]\n",
	"\n",
	"To replace this logo with our own, place your logo in the same directory and modify the file [webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl]"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"nano webapps/xmlui/themes/Mirage2/xsl/core/page-structure.xsl"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Locate this section below"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<a href=\"{$context-path}/\" class=\"navbar-brand\">\n",
	" <img src=\"{$theme-path}images/DSpace-logo-line.svg\" />\n",
	"</a>"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Modify the image name to refer to the image name of your logo"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"NOTE: You need to use an FTP client (eg WinSCP or filezilla) to copy the image from your laptop to the server."
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"### Styling and colors\n",
	"Changing the look and feel of dspace is easy if you know CSS (Cascading Style Sheets). \n",
	"\n",
	"This can all be done from the file [webapps/xmlui/themes/Mirage2/styles/main.css]"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"nano webapps/xmlui/themes/Mirage2/styles/main.css"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"NOTE: Learn to copy from others. If there's a dspace repository that you like how it has been customized, it is no offense looking at the HTML source-code and styling to get ideas on how it has been customized."
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 5. Customizing Input Forms\n",
	"\n",
	"Sometimes it is neccessary to customize input forms to add features, reorder lements or entirely remove them.\n",
	"\n",
	"In this example, we will add Swahili language to one of the language options in the metadata workflow.\n",
	"\n",
	"Configuration for input forms can be found in [config/input-forms.xml].\n",
	"\n",
	"Locate the line with the XML code below:"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<value-pairs value-pairs-name=\"common_iso_languages\" dc-term=\"language_iso\">"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Then add the XML code below as its child element. It is also possible that you can replace a language that you're almost sure you will never use with the new one."
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<pair>\n",
	" <displayed-value>Swahili</displayed-value>\n",
	" <stored-value>sw</stored-value>\n",
	"</pair>"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Save the file and close the file.\n",
	"\n",
	"When you go to submit a new document to dspace, you will now be able to see Swahili as one of the available languages."
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 6. Adding Static Pages\n",
	"\n",
	"Additional static pages (including \\.html) files can be placed in webapps/xmlui/static* directory.\n",
	"To demonstrate this, create a page with the following commands in succession:"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"nano webapps/xmlui/static/my-page.html"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"Then paste the HTML code below, save and close."
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"<!DOCTYPE html>\n",
	"<html lang=\"en\">\n",
	"<head>\n",
	" <meta charset=\"UTF-8\">\n",
	" <title>My DSPace Page</title>\n",
	" <style type=\"text/css\">\n",
	"\tbody{\n",
	"\t background: #eee;\n",
	"\t}\n",
	" </style>\n",
	"</head>\n",
	"<body>\n",
	"<h1>My Static DSpace Page</h1>\n",
	"<table border=\"1\">\n",
	" <tr>\n",
	" <td>blue</td><td>blue</td>\n",
	" </tr>\n",
	" <tr>\n",
	" <td>red</td><td>blue</td>\n",
	" </tr>\n",
	" <tr>\n",
	" <td>black</td><td>blue</td>\n",
	" </tr>\n",
	"</table>\n",
	"</body>\n",
	"</html>\n"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"External style sheets, javascript and images can be refenced with paths relative to this folder"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## PRO-TIP : Search Text Manually\n",
	"\n",
	"If there's a piece of text on a dspace page that you need to modify but don't know which file to edit, run the code below to help you find it."
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"grep -iR \"text you are searching for\" ./"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"This will list all files that contain the text in quotes by searching all files in the current directory and all its subdirectories ignoring case sensitivity."
	]
	}
	],
	"metadata": {
	"kernelspec": {
	"display_name": "Bash",
	"language": "bash",
	"name": "bash"
	}
	},
	"nbformat": 4,
	"nbformat_minor": 2
	}