How to…?

This is a collection of some commonly asked questions on how to accomplish certain things with webgen. If you have an idea for a new howto, don’t hestitate to write me a email!

• create a website?

  You can create the needed structure by hand (which would be not so much to do). However, it’s still easier using the webgen command line tool:

  webgen create -t project -s andreas07 my_site

  This will create a webgen website in the directory my_site using the specified template and style.

• use a website/gallery/sipttra style?

  Just use the webgen command line tool:

  webgen use website_style STYLE_NAME
  webgen use gallery_style STYLE_NAME
  webgen use sipttra_style STYLE_NAME

  Be aware that destination files may be overwritten!

• set plugin parameters?

  You can set plugin parameters for all plugins via the configuration file. For example, say you want to set the File/DefaultHandler:linkToCurrentPage parameter to true, then you would add the following to the configuration file:

  File/DefaultHandler:
    linkToCurrentPage: true

  There is a second possibility for tags: you can set the parameters directly in the tag definition, like this:

  {breadcrumbTrail: {omitLast: true, separator: ' | '}}

• change the default language?

  To use, for example, German as the default language, put the following into the configuration file:

  Core/Configuration:
    lang: de

• set a different content format for page files?

  If you want to change the default content format, you need to add the following to your configuration file (assuming you didn’t set the Core/FileHandler:defaultMetaInfo parameter):

  File/PageHandler:
    defaultMetaInfo:
      blocks: [[content, FORMAT_NAME]]

  This will set the default format to FORMAT_NAME.

  If you just want to change the format for a block, you should do it like this:

  --- content, FORMAT_NAME
    This is the block
  

• set the default meta information for files created by a specific file handler?

  Use the configuration file! For example, to change the default content format to markdown and inMenu to true for page files use the following in your configuration file:

  File/PageHandler:
    defaultMetaInfo:
      blocks: [[content, markdown]]
      inMenu: true

• ignore files in the source directory?

  This can be done using the Core/FileHandler:ignorePaths parameter. For example, to ignore all files starting in core, you would put the following in the configuration file:

  Core/FileHandler:
    ignorePaths: [*/core]

  Be aware that the parameter overwrites the default setting. For more information on which path patterns are supported, have a look a the path pattern documentation!

• change the output name format of page file?

  Set the File/PageHandler:outputNameStyle in the configuration file to globally change how the output names for page files are constructed or use the outputNameStyle meta information to change it only for individual page files!

  For more information have a look at the documentation of the File/PageHandler:outputNameStyle parameter!

• use embedded ruby in page/template files?

  Have a look at the ERB section of the WebPage Format reference!

• modify the template chain?

  First, have a look at the File/TemplateHandler documentation!

  To stop the template chain at a specific template or even at the page file itself, specify a null template in the meta information, like this:

  template: ~

  To nest templates, you just need to specify the template in the meta information section:

  template: my_special.template

  Be aware that if no template meta information is specified for a page or template file, the template handler automatically searches for a default template in directory and the parent directories of the file!

• localize a directory name?

  Just set the directoryName meta information on the localized directory index files!

• provide additional attributes on links to a page file?

  You can specify additional attributes for a page file using the linkAttrs meta information. Take the following page file:

  ---
  title: Tutorial
  inMenu: true
  linkAttrs:
    title: This is a rather large tutorial
    accesskey: D
    tabindex: 5
  ---
  Yippieh, this is my tutorial!
  

  When a link to this page is created the specified attributes always get set on this link!

• add page specific sidebar content?

  There are many ways to accomplish this, I will show only one way here using blocks. Add the following to the sidebar in your default.template:

  <% if node.node_info[:pagedata].blocks.has_key?( 'sidebar' ) %>
    {block: sidebar}
  <% end %>

  This will include the contents of the block sidebar in the sidebar if such a block exists for a page. Then just add a sidebar block to each page file which needs it. Following is such a sample page file:

  This is the main content block
  --- sidebar
  This is the sidebar block and everything in here goes to the sidebar!
  

• use global variables?

  First you need to set some global variables in your configuration file:

  Core/Configuration:
    customVars:
      myVar: This is really nice!
      myOtherVar: another content

  Then you can use the Tag/CustomVar to output the variables:

  {customVar: myVar}

• create XML output?

  This can be achieved manually (by setting the content format of the page file to html and then directly creating the XML elements) or by using the ContentConverter/XmlBuilder plugin !

• use emoticons instead of ASCII smileys?

  Either globally enable an emoticon pack in the configuration file, like this:

  Misc/SmileyReplacer:
    emoticonPack: crystal

  Or enable smiley replacement only on a specific page file using the meta information, like this:

  emoticonPack: crystal

• syntax highlight an included file?

  This can be done using the Tag/IncludeFile plugin. Make sure you have coderay installed! Here is an example which includes a syntax highlighted ruby file:

  {includeFile: {filename: happy.rb, highlight: ruby}}

• create a static menu?

  Have a look at the meta information backing file documentation!

  You can use virtual nodes in the output backing section to define virtually any menu structure you like, including things like having menu entries that point to the same page and links to external pages!