Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:beginner:customization [2016/06/24 14:39]
kjdon
en:beginner:customization [2019/12/05 13:33] (current)
anupama [Customization]
Line 6: Line 6:
 the style, the display of your documents and lists, etc.  the style, the display of your documents and lists, etc. 
  
-xx 
 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 73: Line 72:
 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. 
 +
 +===== Maintaining security when customising GS2 macros =====
 +
 +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.
 +
 +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. ​
 +
 +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]]
 +
 </​TAB>​ </​TAB>​
 </​TABAREA>​ </​TABAREA>​
Line 85: Line 115:
   * [[en:​user:​gs3_sample_format_statements| Sample format statements]]   * [[en:​user:​gs3_sample_format_statements| Sample format statements]]
   * [[en:​user:​themes|Themes]]   * [[en:​user:​themes|Themes]]
 +  * [[en:​user:​interfaces| Customising the Greenstone 3 Interface]]
   * [[en:​user:​gs3_sample_interface_modifications|Sample interface modifications]]   * [[en:​user:​gs3_sample_interface_modifications|Sample interface modifications]]