Example Code

This section shows you some documented examples. Hopefully you can use them as well for your daily work.
They are meant as a small utility-box on which you can build richer functionality.

All the following procedures can be found in the file example.tcl which is distributed with the TrapEd-executable (see Download).

To use the downloaded file, extract it in the directory where the TrapEd-executable lies.
At the beginning of your code put the following line:

 source example.tcl

Afterwards you can simply call the given procedures.
Keep in mind that there is nearly any error-handling in the provided examples. A full-featured error-handling is left for the reader to implement ;-)

You can also provide your examples, if you want to share your code and think it could be usable and useful for others, I would be glad if you email me your code and it will be placed on this page.

Examples

To get you in touch with some basics here are some simple examples:

• Print template-structure
• Print statistics

These are only meant to give you a feeling of how easy it is to develop your own scripts to work with attr-files.
Some more advanced examples are:

• Synchronize with CVS - Check all changed templates into CVS.
• Find a Template, Record, ... by a search-pattern.
• TemplateDoc - Create a html-framework for your template-documentation like javadoc.

Print the template-structure

The following function will print the template-structure to the console or stdout:

 
proc printTemplateStructure {handle projectId {level 0}} {
    set projectName [$handle getAttributeValue $projectId Name]
    puts "[string repeat " " $level] $projectId Project: $projectName"
    foreach id [$handle getIdList Project $projectId] {
        # call recursively
        printTemplateStructure $handle $id [expr $level +4]
    }
    foreach id [$handle getIdList Template $projectId] {
        set templName [$handle getAttributeValue $id Name]
        puts "[string repeat " " [expr $level +4]] $id Template: $templName"
    }
}

Open the API-console by opening a DOS-box in the examples-directory:
C:\> ..\traped.exe -script interactive

And type the following commands into the console:

 
 source example.tcl
 set th [readAttrFile "d:/example.attr"]
 printTemplateStructure $th [$th getRootId]

With sourcing the file example.tcl you get the definition of the procedure printTemplateStructure. The output is printed in the console-window.
Another option is to save the above three lines of code into the file print_templates.tcl, place it into the examples-directory of TrapEd, open a DOS-box in that directory and call:
C:\...\examples> ..\traped.exe -script print_templates.tcl > templates.txt

The output will be printed to the file templates.txt.

Print statistics

To gather some information about an attr-file you can take the following procedure as a start. The procedure is included in the example.tcl-file.

 
proc printStatistics {handle} {
    # count the number of projects/records/templates/files
    set rootId [$handle getRootId]
    foreach type {Template Project File Record} {
        set aId($type) [$handle getIdListRecursive $type $rootId]
        puts "Number of ${type}s: [llength $aId($type)]"
    }
    # find the latest modified template
    set lastTime 0
    set latestModTemplateId ""
    foreach id $aId(Template) {
        if {[$handle getAttributeValue $id LastModTime] > $lastTime} {
            set lastTime [$handle getAttributeValue $id LastModTime]
            set latestModTemplateId $id
        }
    }
    set name [$handle getAttributeValue $latestModTemplateId Name]
    # here you can see how the internal time-format (seconds since 1970)
    # is formated using the command clock  
    puts "Template '$name' was last modified on [clock format $lastTime]."
}

Create a file: print_statistics.tcl with the following code:

 
  source example.tcl
  set handle [readAttrFile "example.attr"]
  printStatistics $handle

and place it in the TrapEd-examples-directory.

Open a DOS-box, change to the example-directory and call:
C:\...\examples> ..\traped.exe -script print_statistics.tcl > statistics.txt

And the statistics will be stored in the file statistics.txt.
Simply adapt the procedure printStatistics to your needs (and to get more useful information.

Synchronize with CVS

The most often problem of Vignette I've heard of is the missing integration with CVS (Concurrent Versions System, see CVS-Home).
With the TrapEd-API you can easy write your own CVS-checkin/out-procedure. You can start with the following example:

 
proc syncCVS {handle dumpDirectory msg} {
    set rootId [$handle getRootId]

    # work in the given directory
    set backupPwd [pwd]
    cd $dumpDirectory

    foreach id [$handle getIdListRecursive Template $rootId] {
        # create the file
        set name [$handle getAttributeValue $id Name]
        set ext [$handle getAttributeValue $id ext]
        set fd [open $name.$ext w+]
        puts -nonewline $fd [$handle getAttributeValue $id body]
        close $fd

        # add or commit to CVS
        if {[catch {exec cvs commit -m $msg $name.$ext} result]} {
            # error while commiting? maybe we must add this file first
            if {[catch {
                exec cvs add $name.$ext
                exec cvs commit -m $msg $name.$ext
            } result]} {
                puts "Adding or Commit of $name.$ext failed: $result"
                continue
            }
        }
        if {[catch {exec cvs update $name.$ext} result]} {
            puts "Updating file failed: $result"
            continue
        }
        # update body in attr-file (to reflect correct $Revision$-Tags ...
        set fd [open $name.$ext r+]
        $handle setAttributeValue $id body [read $fd]
        close $fd
    }
    cd $backupPwd
}

Having a file called doCVS.tcl in the example-directory:

 
source example.tcl
set th [readAttrFile "d:/example.attr"]

# Attention: Be sure that the directory "d:/templates" exist.
syncCVS $th d:/templates "My CVS commit-message for this release."

# overwrite the attr-file to get the updated $Revision$-tags
# into Vignette again
$th writeToFile "d:/example.attr"

And call it like this (in a DOS-box opened in path: "traped-path\example")
C:\> ..\traped.exe -script doCVS.tcl

This will write all the template-code into files in the directory d:/templates (because template-names should be unique, this should not result in a naming-conflict). And afterwards tries to add resp. commit the template to CVS (you have to adapt the cvs-calls if you have an authorization for your CVS).
Afterwards the template-code is updated in the attr-file. This is important to get your CVS-keywords (e.g. $Revision$) updated in Vignette as well.

Because TrapEd can be called batch-like you can simply write an at-job on windows and a cronjob on your server (if you have Unix) to do a nightly transferproject (export), remote-copy it to your TrapEd-maschine (or do the export directly from the TrapEd-machine), run the doCVS.tcl-script and transfer (import) the attr-file again into Vignette.

Find a Template, Record, ...

To find a template by it's name or a search-pattern you can use the following procedure.

 
proc findItemByName {handle search_pattern {projectId ""} {type "Template"}} {
    set lResult {}
    if {$projectId == ""} {
        set projectId [$handle getRootId]
    }
    foreach id [$handle getIdListRecursive $type $projectId] {
        set name [$handle getAttributeValue $id Name]
        if {[string match -nocase $search_pattern $name]} {
            # the name matched the search-pattern:
			# append id to result
            lappend lResult $id
        }
    }
    return $lResult
}

Call it like this:

 
findItemByName $trapedHandle "*misc*"
# will return: example_misc_component example_misc_library