templates

##Introduction##

This page shows how to use templates with Java2word - BETA. Issue 26 . Java2word template solution is an experiment. Some people reported that worked well. Feel free anyone to try it out and post a feedback case you find out something new. Remember volunteers are always welcome.

Dont't forget to check this page out for a full reference about special characters.

Creating the Template##

• Create your template in MS Word
• Add your place holders. Recommended to use camel case. Eg.:

phCompanyName

Don't use "ph_company_name" because MS Word breaks it down in many "runs" and you won't be able to replace.

• Save it as "Microsoft Word 2003 - XML"

#Getting your hands dirty#

Now that you have your template, it is time to do the replacement.

I will copy and past a code snippet from the class /java2word/src/test/java/word/w2004/template/TemplateTest.java:

    @Test
    public void testTemplate() {
        String xmlTemplate = Utils.readFile("src/test/resources/ReleaseNotesTemplate.doc");
        
        xmlTemplate = replacePh(xmlTemplate, "phCompanyName", "EasyWorld - coding for fun pty");
        xmlTemplate = replacePh(xmlTemplate, "phEnv", "Production");
        xmlTemplate = replacePh(xmlTemplate, "phVersion", "1.0 beta");
        xmlTemplate = replacePh(xmlTemplate, "phProjectLeader", "Leonardo Correa");
        
        Table tbl = new Table();
        tbl.addTableEle(TableEle.TH, "Jira Number", "Description");

        tbl.addTableEle(TableEle.TD, "J2W-1234", "Read Templates nicelly");
        tbl.addTableEle(TableEle.TD, "J2W-9999", "Make Java2word funky!!!");

        xmlTemplate = replacePh(xmlTemplate, "phTableIssues", tbl.getContent());
        
        Paragraph p01 = Paragraph.with("1) Stop the server").create();
        Paragraph p02 = Paragraph.with("2) Run the script to deploy the app xxx").create();
        Paragraph p03 = Paragraph.with("3) Start the server").create();
        Paragraph p04 = Paragraph.with("4) Hope for the best").create();
        
        String instructions = p01.getContent() + p02.getContent() + p03.getContent() + p04.getContent();
        
        //Workaround: phInstructions is already inside a 'text' fragment. 
        //If you know the template, you can remove the whole element and add all Paragraphs
        //* Table above doesn't need workaround because table can be normally inside a paragraph.
        xmlTemplate = replacePh(xmlTemplate, "phInstructions", instructions); 
        
        xmlTemplate = replacePh(xmlTemplate, "phDateTime", new Date().toString());
        
        TestUtils.createLocalDoc(xmlTemplate);        
    }

    /***
     * Does the Place Holder replacement but LOGS when can not find place holder. 
     * This method is here to show how you could eventually replace placeholders. It is not in the library.
     * @param base Base String that contains the big XML with all placeholders
     * @param placeHolder the actual place holder
     * @param value value to take place
     * @return the new string with place holder replaced
     */
    private String replacePh(String base, String placeHolder, String value) {
        if(!base.contains(placeHolder)) {
            //don't want to use log now because I want to keep it simple...
            System.out.println("### WARN: couldn't find the place holder: " + placeHolder);
            return base;
        }        
        return base.replace(placeHolder, value);
    }

The code above takes this ReleaseNotesTemplate.doc(http://code.google.com/p/java2word/downloads/detail?name=ReleaseNotesTemplate.doc&can=2&q=#makechanges) and produces this result is here templateResult.doc(http://code.google.com/p/java2word/downloads/detail?name=templateResult.doc&can=2&q=).

The method replacePh() is very simple but important at the same time. It replaces but prints a warning message when can't find the place holder. If you see this "warning" messages it means that your template has got some "breakdown" text and you may have to manually fix your template by editing the template as XML.

Also see the comment about the workaround. Table can comfortably be inside a paragraph. But you can not have one <w:t> inside other. What I do is remove the whole element and replace with many paragraphs.

This is is obviously a huge workaround but this library is already a workaround itself.... hehehehe - it doesn't bother me at all...

##Original Idea##

First I tried to use a place holder like this: {ph_version}. But the problem was the MS Word was breaking down to this:

            <w:p wsp:rsidR="000E7286" wsp:rsidRDefault="00900844">
                  <w:r wsp:rsidRPr="005B7C3D">
                        <w:rPr>
                              <w:b/>
                        </w:rPr>
                        <w:t>Version:</w:t>
                  </w:r>
                  <w:r>
                        <w:t> {ph</w:t>
                  </w:r>
                  <w:r wsp:rsidR="000E7286">
                        <w:t>_version}
                  </w:r>
            </w:p>

I don't know why MS word is doing this, making impossible to replace the place holder properly. So when you create your template MAKE SURE ALL PLACE HOLDERS ARE IN THE SAME SEQUENCE - NOT BREAK DOWN IN "RUNS"(<w:r>)

Have a try, create an issue if you have any suggestion or problem.

#Related Issues/Comments#

Issue 79(http://code.google.com/p/java2word/issues/detail?id=79) , Issue 70(http://code.google.com/p/java2word/issues/detail?id=70)

thanks for using Java2word.

cheers Leonardo Correa