Greenstone Wiki

User Tools

Site Tools

You are here: index » en » beginner » customization
en:beginner:customization

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:beginner:customization [2016/06/24 02:39] – [Useful Links for Customisation] kjdonen:beginner:customization [2023/03/13 20:51] (current) – [Customizations] kjdon
Line 1: Line 1:
 +
 +
 ====== Customization ====== ====== Customization ======
 //**Part of the [[en:beginner:index|Greenstone Beginner's Guide]]**// \\ //**Part of the [[en:beginner:index|Greenstone Beginner's Guide]]**// \\
Line 8: Line 10:
 There are a few pages that, though not directly concerned with customization,  There are a few pages that, though not directly concerned with customization, 
 can be very useful during the process: can be very useful during the process:
-  * The [[en:directory_structure|directory structure]] page can help you locate important files and folders in your installation. + <!-- * The [[en:directory_structure|directory structure]] page can help you locate important files and folders in your installation.--> 
-  * Understanding how [[en:user:urls|Greenstone URLs]] work, including CGI arguments, can help you create links to various pages in your collection.+  * Understanding how Greenstone URLs ([[en:user:gs3_urls|gs3]], [[en:user:gs2_urls|gs2]]) work, including CGI arguments, can help you create links to various pages in your collection.
   * Knowing the [[en:user:configuration_files|files that configure]] specific aspects of your installation is very important as you begin to customize.   * Knowing the [[en:user:configuration_files|files that configure]] specific aspects of your installation is very important as you begin to customize.
  
Line 16: Line 18:
  
  
-<TABAREA tabs="Greenstone3,Greenstone2"> +=====Greenstone3===== 
-<TAB> +==== Site, interfaces, and libraries ====
-===== Site, interfaces, and libraries =====+
 Sites and interfaces contain the content and presentation information, respectively,  Sites and interfaces contain the content and presentation information, respectively, 
 for the digital library.   for the digital library.  
Line 26: Line 27:
 You can have multiple separate sites in a single Greenstone3 installation. You can have multiple separate sites in a single Greenstone3 installation.
  
-An **[[en:user:interfaces|interface]]** is a set of images (and, potentially, CSS and Javascript) along+An **[[en:user:interfaces|interface]]** is a set of images, Css and Javascript along
 with a set of XSLT files used for translating XML output from the library into an appropriate form --  with a set of XSLT files used for translating XML output from the library into an appropriate form -- 
 HTML generally. XSLT (and therefore every Greenstone interface) is built around things called **templates**, which will HTML generally. XSLT (and therefore every Greenstone interface) is built around things called **templates**, which will
 tell Greenstone how to display pages depending on the content for that page (e.g. a document's metadata, tell Greenstone how to display pages depending on the content for that page (e.g. a document's metadata,
 the names of the collections in your site, what browsing classifier have been defined, etc.).  the names of the collections in your site, what browsing classifier have been defined, etc.). 
 +
 +A **library** is a combination of one site with one interface - in technical terms, each library is a servlet.
 +
 +You can create any number of interfaces in your Greenstone3 installation, which is especially useful for when you want to present the same content in different ways. In addition, multiple sites can make use of the same interface. The servlet configuration determines which libraries will be presented.
  
 //If all of that sounds really confusing, don't worry!  //If all of that sounds really confusing, don't worry! 
 Unless you want to make extreme changes to an interface (or define your own), Unless you want to make extreme changes to an interface (or define your own),
  you can largely avoid XSLT. //  you can largely avoid XSLT. //
 +
 +==== Customizations ====
  
 While the interfaces (i.e. the files that dictate how each page looks) themselves are separate from the content, you can override any part of  While the interfaces (i.e. the files that dictate how each page looks) themselves are separate from the content, you can override any part of 
Line 40: Line 47:
 make modifying or overriding an interface easier: make modifying or overriding an interface easier:
   * **[[en:user:themes|Themes]]**, are the easiest way to change how your library looks. The default Greenstone3 interface is built using JQuery themes, which allow you to change the color-scheme (as well as things like roundness of corners) effortlessly. While even advanced users will find themes useful, they are especially valuable for non-technical users, because they require //absolutely no// knowledge of CSS, HTML, or XSL   * **[[en:user:themes|Themes]]**, are the easiest way to change how your library looks. The default Greenstone3 interface is built using JQuery themes, which allow you to change the color-scheme (as well as things like roundness of corners) effortlessly. While even advanced users will find themes useful, they are especially valuable for non-technical users, because they require //absolutely no// knowledge of CSS, HTML, or XSL
-  * **[[en:user:gs3_format_statements|Format statements]]**: In many cases, if you do not know XSL, you can instead use [[en:user:gs3_format_statements|Greenstone's statement format (''gsf'')]], which Greenstone will translate (behind-the-scenes) into XSL. ''gsf'' syntax is XML-based. (If you don't know XML, don't worry; it looks and acts very similarly to HTML.)+  * **[[en:user:gs3_format_statements|Format statements]]**: In many cases, if you do not know XSL, you can instead use [[en:user:gs3_format_statements|Greenstone's format elements (''gsf'')]], which Greenstone will translate (behind-the-scenes) into XSL. ''gsf'' syntax is XML-based. (If you don't know XML, don't worry; it looks and acts very similarly to HTML.)
   * The GLI's **Format Features** section: The GLI provides an easy way to override parts of interface on a collection-level. Instead of having to create your own XSL files, you can type templates into the Format Features section of the Format panel.    * The GLI's **Format Features** section: The GLI provides an easy way to override parts of interface on a collection-level. Instead of having to create your own XSL files, you can type templates into the Format Features section of the Format panel. 
  
-You can create any number of interfaces in your Greenstone3 installation, which is especially useful for when you want to  +==== Useful Links====
-present the same content in different ways. For example, you may want to provide two interfaces +
-for your sites: one interface for visitors using computers and another interface for mobile users. In addition, +
-multiple sites can make use of the same interface. +
  
-Finally, every site-interface combination you create is considered a **library**  +  * [[en:gli:format_panel| GLI's format panel]] 
-(in technical terms, each library is actually a servlet). +  * [[en:user:gs3_format_statements|Format statements]] 
-</TAB> +  * [[en:user:gs3_list_of_format_options|Full list of Format options]] 
-<!-- ################################################################################## +  * [[en:user:gs3_sample_format_statements| Sample format statements]] 
-####################################################################################### +  * [[en:user:themes|Themes]] 
-#######################################################################################--> +  * [[en:user:interfaces| Customising the Greenstone 3 Interface]] 
-<TAB> +  * [[en:user:gs3_sample_interface_modifications|Sample interface modifications]] 
-===== Collection level vs. library level =====+ 
 +//**Now that you know the basics of using and customizing Greenstone, there are a few other features, functions, and resources you should be aware of. The final section of this Beginner's Guide presents [[en:beginner:additional_topics|additional Greenstone topics]].**// 
 + 
 +=====Greenstone2===== 
 +==== Collection level vs. library level ====
  
 Customization can be done at either collection level or library level. Any changes made in the GLI Customization can be done at either collection level or library level. Any changes made in the GLI
Line 62: Line 70:
 enacted on a collection or library basis.  enacted on a collection or library basis. 
  
-===== Format Statements =====+==== Format Statements ====
 The //content// of a Greenstone collection is handled by [[en:user:gs2_format_statements|format statements]],  The //content// of a Greenstone collection is handled by [[en:user:gs2_format_statements|format statements]], 
 which can be modified in the GLI (under ''Format -> Format Features''). So, if you want to change how documents appear which can be modified in the GLI (under ''Format -> Format Features''). So, if you want to change how documents appear
Line 68: Line 76:
 to make changes. to make changes.
  
-===== Macros =====+==== Macros ====
  
 Greenstone2 is built on [[en:user:macros|macros]], which look like ''_this_'' and basically stand for Greenstone2 is built on [[en:user:macros|macros]], which look like ''_this_'' and basically stand for
 a block of text or code.  a block of text or code. 
-</TAB> 
-</TABAREA> 
  
-===== Useful Links for Customisation =====+==== Maintaining security when customising GS2 macros ====
  
-  * [[en:gli:format_panel| GLI's format panel]]+A large part of Greenstone 2's security against cross-site scripting (XSS) is implemented in Greenstone 2.87+ in the macros files. This means that if you are customising it by reusing macros such as in new forms or paragraphs, you will need to be aware of how to do so in a secure way.
  
-**Greenstone3:** +Every macro variable now has additional variants of itself: variants that are safe to use in an HTML context, in an HTML attribute context, CSS context, URL context, JavaScript context and SQL context. 
-  * [[en:user:gs3_format_statements|Format statements]] +
-  * [[en:user:gs3_list_of_format_options|Full list of Format options]] +
-  * [[en:user:gs3_sample_format_statements| Sample format statements]] +
-  * [[en:user:themes|Themes]] +
-  * [[en:user:gs3_sample_interface_modifications|Sample interface modifications]]+
  
-**Greenstone2:**+The additional variants of each variable are denoted by the suffixes: 
 +<code>Htmlsafe, Attrsafe, Csssafe, Urlsafe, Jssafe, Sqlsafe</code> 
 +The variable name suffixes of these additional variants' indicate the context in which each is to be used.  
 +// 
 +For example//, the ''_cgiargq_'' variable has the following variants: 
 +<code>_cgiargqHtmlsafe_ 
 +_cgiargqAttrsafe_ 
 +_cgiargqCsssafe_ 
 +_cgiargqUrlsafe_ 
 +_cgiargqJssafe_ 
 +_cgiargqSqlsafe_</code> 
 + 
 +In reusing existing macros when you want to customise Greenstone 2 macro files, carefully select the appropriate variant of the variable you want depending on the context in the file where that variable needs to be used. 
 + 
 +In some cases, this can be straightforward: if it is going into an HTML attribute, use the ''Attrsafe'' variant. If it's going to be (part of) a URL, use the Urlsafe version. If it goes into regular JavaScript code, use the Jssafe version, etc. 
 + 
 +An example of a more complex case would be where Javascript produces HTML. If the variable is part of the HTML page produced by some JavaScript code, you need to use the ''Htmlsafe'' variant instead of the Jssafe variant. 
 + 
 +If you make your customisations consciously and sensibly, your modified macro files will continue to keep Greenstone 2's security intact. 
 + 
 +For more information: 
 +  * [[https://www.owasp.org/index.php/Cross-site_Scripting_%28XSS%29|OWASP Cross Site Scripting (XSS) page]] 
 +  * [[https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html|OWASP XSS cheat sheet]] 
 + 
 + 
 + 
 +====Useful Links ==== 
 + 
 +  * [[en:gli:format_panel| GLI's format panel]]
   * [[en:user:gs2_format_statements|Format statements]]   * [[en:user:gs2_format_statements|Format statements]]
   * [[en:user:gs2_sample_format_statements| Sample format statements]]   * [[en:user:gs2_sample_format_statements| Sample format statements]]
Line 94: Line 123:
  
 //**Now that you know the basics of using and customizing Greenstone, there are a few other features, functions, and resources you should be aware of. The final section of this Beginner's Guide presents [[en:beginner:additional_topics|additional Greenstone topics]].**// //**Now that you know the basics of using and customizing Greenstone, there are a few other features, functions, and resources you should be aware of. The final section of this Beginner's Guide presents [[en:beginner:additional_topics|additional Greenstone topics]].**//
 +
en/beginner/customization.1466735963.txt.gz · Last modified: 2016/06/24 02:39 by kjdon