Differences

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

--- en:user:macros [2014/04/13 23:52] – external edit 127.0.0.1
+++ en:user:macros [2023/03/13 01:46] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-<TABAREA tabs="Greenstone2">
-<TAB>
-===== Macros =====
+====== Greenstone 2 Macros ======
 Macros define either strings on the interface or variables utilized in C++ codes. By using macros, users can easily customize the user interface without changing any C++ code.
-<!-- id:700 -->The entire Greenstone user interface is controlled by macros which reside in the //GSDLHOME/macros// directory. They are written in a language designed especially for Greenstone, and are used run time to generate web pages. Translating the macro language into html is the last step in displaying a page. Thus changes to a macro file affect the display immediately, making experimentation quick and easy. All macro files used by Greenstone are listed in //GSDLHOME/etc/main.cfg// and are loaded every time it starts. One exception to this is when using the Windows Local Library; in this case it is necessary to restart the process.
+The entire Greenstone user interface is controlled by macros which reside in the //GSDLHOME/macros// directory. They are written in a language designed especially for Greenstone, and are used run time to generate web pages. Translating the macro language into html is the last step in displaying a page. Thus changes to a macro file affect the display immediately, making experimentation quick and easy. All macro files used by Greenstone are listed in //GSDLHOME/etc/main.cfg// and are loaded every time it starts. One exception to this is when using the Windows Local Library; in this case it is necessary to restart the process.
-<!-- id:701 -->Web pages are generated on the fly for a number of reasons, and the macro system is how Greenstone implements the necessary flexibility. Pages can be presented in many languages, and a different macro file is used to store all the interface text in each language. When Greenstone displays a page the macro interpreter checks a language variable and loads the page in the appropriate language (this does not, unfortunately, extend to translating document content). Also, the values of certain display variables, like the number of documents found by a search, are not known ahead of time; these are interpolated into the page text in the form of macros.
+Web pages are generated on the fly for a number of reasons, and the macro system is how Greenstone implements the necessary flexibility. Pages can be presented in many languages, and a different macro file is used to store all the interface text in each language. When Greenstone displays a page the macro interpreter checks a language variable and loads the page in the appropriate language (this does not, unfortunately, extend to translating document content). Also, the values of certain display variables, like the number of documents found by a search, are not known ahead of time; these are interpolated into the page text in the form of macros.
 ==== The macro file format ====
-<!-- id:703 -->Macro files have a //.dm// extension. Each file defines one or more //packages//, each containing a series of macros used for a single purpose. Like classifiers and plugins, there is a basis from which to build macros, called //base.dm// ; this file defines the basic content of a page.
+Macro files have a //.dm// extension. Each file defines one or more //packages//, each containing a series of macros used for a single purpose. Like classifiers and plugins, there is a basis from which to build macros, called //base.dm// ; this file defines the basic content of a page.
-<!-- id:704 -->Macros have names that begin and end with an underscore, and their content is defined using curly brackets. Content can be plain text, html (including links to Java applets and JavaScript), macro names, or any combination of these. This macro from //base.dm// defines the content of a page in the absence of any overriding macro:
+Macros have names that begin and end with an underscore, and their content is defined using curly brackets. Content can be plain text, html (including links to Java applets and JavaScript), macro names, or any combination of these. This macro from //base.dm// defines the content of a page in the absence of any overriding macro:
 <code>
@@ Line 19: / Line 20: @@
 </code>
-<!-- id:705 -->The page will read “Oops” at the top, and //_textdefaultcontent_//, which is defined, in English, to be //The requested page could not be found. Please use your browsers 'back' button or the above home button to return to the Greenstone Digital Library,// and in other languages to be a suitable translation of this sentence.
+The page will read “Oops” at the top, and //_textdefaultcontent_//, which is defined, in English, to be //The requested page could not be found. Please use your browsers 'back' button or the above home button to return to the Greenstone Digital Library,// and in other languages to be a suitable translation of this sentence.
-<!-- id:706 -->//_textdefaultcontent_// and //_content_// both reside in the //global// package because they are required by all parts of the user interface. Macros can use macros from other packages as content, but they must prefix their names with their package name. For example,
+//_textdefaultcontent_// and //_content_// both reside in the //global// package because they are required by all parts of the user interface. Macros can use macros from other packages as content, but they must prefix their names with their package name. For example,
 <code>
@@ Line 27: / Line 28: @@
 </code>
-<!-- id:707 -->comes from //english.dm//, and is used as the default description of a collection. It is part of the //global// package, but //_numdocs_// and //_builddate_// are both in the //about// package—hence the //about:// preceding their names.
+comes from //english.dm//, and is used as the default description of a collection. It is part of the //global// package, but //_numdocs_// and //_builddate_// are both in the //about// package—hence the //about:// preceding their names.
-<!-- id:708 -->Macros often contain conditional statements. They resemble the format string conditional described above, though their appearance is slightly different. The basic format is //_If_(x,y,z)//, where //x// is a condition, //y// is the macro content to use if that condition is true, and //z// the content if it is false. Comparison operators are the same as the simple ones used in Perl (less than, greater than, equals, not equals). This example from //base.dm// is used to determine how to display the top of a collection's //about// page:
+Macros often contain conditional statements. They resemble the format string conditional described above, though their appearance is slightly different. The basic format is //_If_(x,y,z)//, where //x// is a condition, //y// is the macro content to use if that condition is true, and //z// the content if it is false. Comparison operators are the same as the simple ones used in Perl (less than, greater than, equals, not equals). This example from //base.dm// is used to determine how to display the top of a collection's //about// page:
 <code>
@@ Line 41: / Line 42: @@
 </code>
-<!-- id:709 -->This looks rather obscure. //_iconcollection_// resolves to the empty string if the collection doesn't have an icon, or the filename of an image. To paraphrase the above code: If there is a collection image, display the //About this Collection// page header (referred to by //_httppageabout_//) and then the image; otherwise use the alternative display //_imagecollectionv_//.
+This looks rather obscure. //_iconcollection_// resolves to the empty string if the collection doesn't have an icon, or the filename of an image. To paraphrase the above code: If there is a collection image, display the //About this Collection// page header (referred to by //_httppageabout_//) and then the image; otherwise use the alternative display //_imagecollectionv_//.
-<!-- id:710 -->Macros can take arguments. Here is a second definition for the //_imagecollection_// macro which immediately follows the definition given above in the //base.dm// file:
+Macros can take arguments. Here is a second definition for the //_imagecollection_// macro which immediately follows the definition given above in the //base.dm// file:
 <code>
@@ Line 49: / Line 50: @@
 </code>
-<!-- id:711 -->The argument //[v=1]// specifies that the second definition is used when Greenstone is running in text-only mode. The language macros work similarly—apart from //english.dm//, because it is the default, all language macros specify their language as an argument. For example,
+The argument //[v=1]// specifies that the second definition is used when Greenstone is running in text-only mode. The language macros work similarly—apart from //english.dm//, because it is the default, all language macros specify their language as an argument. For example,
 <code>
@@ Line 55: / Line 56: @@
 </code>
-<!-- id:712 -->appears in the English language macro file, whereas the German version is
+appears in the English language macro file, whereas the German version is
 <code>
@@ Line 61: / Line 62: @@
 </code>
-<!-- id:713 -->The English and German versions are in the same package, though they are in separate files (package definitions may span more than one file). Greenstone uses its //l// argument at run time to determine which language to display.
+The English and German versions are in the same package, though they are in separate files (package definitions may span more than one file). Greenstone uses its //l// argument at run time to determine which language to display.
 <imgcaption figure_part_of_the_aboutdm_macro_file|%!-- id:714 --%Part of the //about.dm// macro file ></imgcaption>
@@ Line 89: / Line 90: @@
-<!-- id:715 -->As a final example, Figure <imgref figure_part_of_the_aboutdm_macro_file> shows an exerpt from the macro file //about.dm// that is used to generate the “About this collection” page for each collection. It shows three macros being defined, //_pagetitle_//, //_content_// and //_textabout_//.
+As a final example, Figure <imgref figure_part_of_the_aboutdm_macro_file> shows an exerpt from the macro file //about.dm// that is used to generate the “About this collection” page for each collection. It shows three macros being defined, //_pagetitle_//, //_content_// and //_textabout_//.
 ==== Using macros ====
-<!-- id:717 -->Macros are powerful, and can be a little obscure. However, with a good knowledge of html and a bit of practice, they become a quick and easy way to customise your Greenstone site.
+Macros are powerful, and can be a little obscure. However, with a good knowledge of html and a bit of practice, they become a quick and easy way to customise your Greenstone site.
-<!-- id:718 -->For example, suppose you wanted to create a static page that looked like your current Greenstone site. You could create a new package, called //static//, for example, in a new file, and override the //_content_// macro. Add the new filename to the list of macros in //GSDLHOME/etc/main.cfg// which Greenstone loads every time it is invoked. Finally, access the new page by using your regular Greenstone URL and appending the arguments //?a=p&p=static// (e.g. //http:%%//%%servername/cgi-bin/library?a=p&p=static//).
+For example, suppose you wanted to create a static page that looked like your current Greenstone site. You could create a new package, called //static//, for example, in a new file, and override the //_content_// macro. Add the new filename to the list of macros in //GSDLHOME/etc/main.cfg// which Greenstone loads every time it is invoked. Finally, access the new page by using your regular Greenstone URL and appending the arguments //?a=p&p=static// (e.g. //http:%%//%%servername/cgi-bin/library?a=p&p=static//).
-<!-- id:719 -->To change the “look and feel” of Greenstone you can edit the //base// and //style// packages. To change the Greenstone home page, edit the //home// package (this is described in the //Greenstone Digital Library Installer's Guide//). To change the query page, edit //query.dm//.
+To change the “look and feel” of Greenstone you can edit the //base// and //style// packages. To change the Greenstone home page, edit the //home// package (this is described in the //Greenstone Digital Library Installer's Guide//). To change the query page, edit //query.dm//.
-<!-- id:720 -->Experiment freely with macros. Changes appear instantly, because macros are interpreted as pages are displayed. The macro language is a useful tool that can be used to make your Greenstone site your own.
+Experiment freely with macros. Changes appear instantly, because macros are interpreted as pages are displayed. The macro language is a useful tool that can be used to make your Greenstone site your own.
@@ Line 193: / Line 194: @@
     * [[en:user:sample_macros#Add footer that sticks to the bottom of the page and has two columns]]
   * [[http://wiki.greenstone.org/wiki/images/c/cb/Customizing_GSDL.pdf|Easy Ways to Customize the Display of Greenstone Pages]] //K Rajasekharan// and //K M Nafala//
-</TAB>
-</TABAREA>