Xilize automatically locates and processes several special files (if they are present) in addition to normal *.xil source files. This page describes the ones used to create the "Xilize by Example" documentation.
The navigation bars, signatures used to generate the source listing are declared in dir.config, header.xilinc, footer.xilinc, thus they do not appear in the listing.
If present in the current directory or any of its parents, this file is included at the beginning of every *.xil file.
define. favicon ${_ProjectRoot_}img/xi16x16.png
xmlcom. ##### top navigation bar #####
p(#xilizeLogo). !${_ProjectRoot_}img/xiLogo64.png (jump to download
page)!:xildownload
div(#header). {{
div(navbar). {{
navbar(nav).
}}
}}
xmlcom. &{repeat(85,"=");}
tranaslation of ${_DirLabelList_}/${_FileNameXil_}
divStart(#central).
xmlcom is the standard signature for creating XML comments.
navbar is a custom signature to create the navigation bar. Note the use of the standard modifier syntax to assign "nav" to the start tag attribute "class".
If present in the current directory or any of its parents, this file is included at the end of every *.xil file.
xmlcom. {{
end translation of ${_DirLabelList_}/${_FileNameXil_}
================================================================================
##### source listing #####
}}
div(listing). {{
h2. source for ${_DirLabelList_} :: ${_FileNameXil_}
xilListing. ${_FilePathXil_}
--Long lines are wrapped in this listing.
Use your web browser's "View Page Source" feature to examine the HTML--
}}
divEnd.
xmlcom. ##### bottom navigation bar #####
xilcom. navbar is set by the custom signature "navbar" in header.xilinc
>xil> km. ${navbar}
include. ${_Root_}/footer.xilinc
xmlcom: standard signature for XML comments.
xilcom: standard signature for Xilize source comments.
div: standard signature for HTML <div> element.
xilListing: custom signature for including listing Xilize sources in these pages.
km.: standard signature for applying only key and macro translation.
${navbar}: refers to "navbar" key set by the navbar custom signature in the header.xilinc. See above. Since the navigation bar is identical in the header and footer, we create it once and assign it to a key. A key definition created in a file is local to that file. (Note: keys created in a dir.xilconfig are available to all files it's directory and subdirectories.)
If present in the current directory, this file is processed. The definitions and custom signatures it contains are availabe to all files and subdirectories unless overridden in a subdirectory's dir.config file.
Since all project directories are scanned prior to translation, all dir.xilconfig files are processed before any *.xil file.
xilcom. configuration for test directory branch
xilcom. these signatures are modified from those in the project root
define. _WarnOnSigOverride_ false
signature. xilListing
exampleFile("listing",80)
signature. bshListing
exampleFile("bshListing",90)
signature. navbar
navBar()
xilcom. the example signature is a shortcut for "div(example)."
signature. example
block.translateAs("div", "(example)");
xilcom: standard signature for Xilize source comments.
signature: standard signature for declaring a custom signature.
define: standard signature for assigning a value to a key. If the key exists, its value is overriden in the current scope. The scope of a dir.xilconfig file is the current directory, its subdirectories, and all the files they contain. Xilize sets _DirLabel_ to the name of the directory. We override that here to provide something more meaningful.
See BeanShell for an explanation of custom signatures and macros.
Xilize loads any *.bsh it finds when scanning directories. Functions in these files are available for use in custom signatures and macros in the current directory, its subdirectories, and all the files they contain.
/*****
BeanShell functions used in custom signatures to build the "Xilize by Example"
documentation. See the Xilize javadocs for Signature, Task (and TaskFile and
TaskDir), and Block for the api for "sig", "task", and "block" objects which
are set by Xilize prior to calling custom signature code. Also set is "text", a
String object.
Trivial examples of BeanShell use can be found in the BeanShell subdirectory.
*****/
/*
navBar() is used in a custom signature defined in dir.xilconfig which in turn
is used in header.xilinc. It's side effect of setting a key is used in
footer.xilinc.
creates a table containing navigation links.
Note, it depends on each directory containing an index.xil file.
Note, too, there are more clever ways of doing this, but this way highlights several
parts of the Xilize API.
*/
navBar() {
// the table will contain one row
StringBuilder sb = new StringBuilder();
// "task" is always set by Xilize before BeanShell code to the current node the tree
// of directory and file task objects.
// _ProjectRoot_ is a native key set to the relative path from the current file
// to the root of the tree. Note how it is prepended to some file paths.
String pr = task.value("_ProjectRoot_");
// the project root key is only empty when the current file is in the project root
// directory
boolean isRoot = pr.equals("./");
// _Prev_ is a native key set to the previous file in the page
// ordering within a directory. _Next_ is set to the next file in the ordering.
// Ordering is alphabetical unless a page.xilconfig file is present.
boolean pn = task.isDefined("_Prev_"); // then _Next_ is defined too
// the first cell in the table is a collection of linked images. Because there is no
// whitespace between them the embedded markup is used ('[' and ']'). Note the
// prepending of the relative path to the project root.
int cellspan = 1;
if( pn || !isRoot ) {
cellspan++;
sb.append("|(arrows) ");
if( task.getDepth() > 1 ) {
sb.append( "!- "+pr+"img/2uparrow.png (top of tree)!:"
+pr+"index.html" );
}
if( pn ) {
sb.append( " !- "+pr+"img/1leftarrow.png (previous page)!:${_Prev_}" );
sb.append( " !- "+pr+"img/1rightarrow.png (next page)!:${_Next_}" );
}
if( !isRoot ) {
sb.append( " !- "+pr
+"img/1uparrow.png (up to parent topic)!:../index.html" );
}
}
// the next cell is a list of directories from the root to the current directory.
// _DirLabelListLinked_ is a native key that contains that list with each label
// linked to its directory's index.html file
sb.append(" |(breadcrumbs) "+ task.value("_DirLabelListLinked_"));
// if the current file's parent directory has subdirectories, we add a cell
// with the a list of those subdirectories, each linked to its index.html file
TaskDir td = task.parentDir();
if( td.hasSubDirs() ) {
sb.append(" |(subdir) " + td.value("_SubDirListLinked_") );
cellspan++;
}
// convert the string we've built to a block, pass the modifiers from the signature
// object ("sig" set by Xilize prior to executing a custom signature) to the new
// block's signature.
int ln = block.getLineNumber();
Block b = new Block(task, ln, sb.toString());
b.getSignature().setMods(sig.getMods());
// if the current file's parent directory has more than one page, we add a row to
// table with a list of the page numbers. Each of the numbers has a link to its
// page except for the one corresponding to the current file.
// Note: the addition of cell column span modifiers and that '\' is escaped because
// this is a Java String expression.
if( td.pageCount() > 1 ) {
b.addLine( ++ln, "|(pagenums)\\"+ cellspan+" "+ td.pageListLinked(task) );
}
//translate the block
b.translate();
// lastly we (1) define the key "navbar" so it can be used in the footer for this
page
// and then (2) return the translation of the block. getBody() retrieves the
translation
task.define("navbar", b.getTranslation());
return b.getTranslation();
}
/*
exampleFile() is used in custom signatures defined in dir.xilconfig.
demonstrates the text of the block being used essentially as a passed
parameter. The function expects the first line of text to contain a relative
path. The text of the file it finds will be "included" in the *.xil source file
within the the html tags shown below.
Notes:
task.markupKeyMacro() translates keys and macros (${} and &{}) in its String argument.
sig.insertAttributes() adds tag attributes from any signature modifiers present
to the first tag in its argument, while preserving any existing attributes.
task.inlineMarkupUnkindChar() replaces &, <, and > with their character entites rep
(& < and >). Required to generate propper HTML.
Files.read() reads a file, optionally wrapping its lines. The Files class in
com.centeredwork.xilize contains a set of static utility methods. Don't confuse
it with java.io.File.
Parameters:
"cls" is a css class name
if "wrap" > 0 lines are wrapped at column "wrap"
*/
exampleFile(cls, wrap) {
// by first translating any keys and macros on the text line we allow those to be
used
// to specify the path. Input error checking is left to the exception handler.
String path = task.markupKM(text);
File file = Files.localFile( path, task.parentDir().getPath() );
return sig.insertAttributes("<pre class=\""+cls+"\">")
+ task.markupU(Files.read(file, wrap))
+ "</pre>";
}
// used to display example use of macros. The only other way to do this reliably is to
// substitute a character/nummeric entity for '{'.
exmacro() { "@&{"+text+"}@"; }
// creates an "next" image link to the next page, (no error check, bad results if there
// is no next page)
next() {
return "[!- "+task.value("_ProjectRoot_")+"img/1rightarrow.png (next page)!:"
+task.value("_Next_")+"]";
}
// returns a string consisting of "s" repeated "n" times
repeat(int n, String s) {
StringBuilder sb = new StringBuilder(n*s.length());
for( int i = 0; i < n; i++ )
sb.append(s);
return sb.toString();
}
// :indentSize=4:mode=beanshell:
The navigation bar at the top and bottom of each page was developed as an experiment in writing custom signatures. The BeanShell code for it is in the listing for test.bsh above.
about these Pages
Xilize automatically locates and processes several special files (if they are
present) in addition to normal @*.xil@ source files. This page describes the
ones used to create the "Xilize by Example" documentation.
The navigation bars, signatures used to generate the source listing are declared
in dir.config, header.xilinc, footer.xilinc, thus they do not appear in the
listing.
toc. 2
h2. special files
h3(#head). header.xilinc
If present in the current directory or any of its parents, this file is included
at the beginning of every @*.xil@ file.
xilListing. ${_ProjectRoot_}header.xilinc
@xmlcom@ is the standard signature for creating XML comments.
@navbar@ is a custom signature to create the navigation bar. Note the use of
the standard modifier syntax to assign "nav" to the start tag attribute
"class".
h3. footer.xilinc
If present in the current directory or any of its parents, this file is included
at the end of every @*.xil@ file.
xilListing. ../footer.xilinc
@xmlcom@: standard signature for XML comments.
@xilcom@: standard signature for Xilize source comments.
@div@: standard signature for HTML @<div>@ element.
@xilListing@: custom signature for including listing Xilize sources in these
pages.
@km.@: standard signature for applying only key and macro translation.
<code>${navbar}</code>: refers to "navbar" key set by the @navbar@ custom
signature in the @header.xilinc@. See "above":#head. Since the navigation bar
is identical in the header and footer, we create it once and assign it to a key.
A key definition created in a file is local to that file. (Note: keys created
in a @dir.xilconfig@ are available to all files it's directory and
subdirectories.)
h3. dir.xilconfig
If present in the current directory, this file is processed. The definitions
and custom signatures it contains are availabe to all files and subdirectories
unless overridden in a subdirectory's dir.config file.
Since all project directories are scanned prior to translation, all
dir.xilconfig files are processed before any *.xil file.
xilListing. ../dir.xilconfig
@xilcom@: standard signature for Xilize source comments.
@signature@: standard signature for declaring a custom signature.
@define@: standard signature for assigning a value to a key. If the key exists,
its value is overriden in the current scope. The scope of a dir.xilconfig file
is the current directory, its subdirectories, and all the files they contain.
Xilize sets @_DirLabel_@ to the name of the directory. We override that here to
provide something more meaningful.
h3. test.bsh
See "BeanShell":index.html for an explanation of custom signatures and macros.
Xilize loads any @*.bsh@ it finds when scanning directories. Functions in these
files are available for use in custom signatures and macros in the current
directory, its subdirectories, and all the files they contain.
bshListing. ${_ProjectRoot_}xdocs.bsh
h2. the navigation bar
The navigation bar at the top and bottom of each page was developed as an
experiment in writing custom signatures. The BeanShell code for it is in the
listing for @test.bsh@ above.
Long lines are wrapped in this listing.
Use your web browser's "View Page Source" feature to examine the HTML
