Tipes Mail Merge Operasie

Die hoofgedagte van Mail Merge is om outomaties’n dokument of verskeie dokumente te skep gebaseer op jou sjabloon en data wat van jou databron afgelei is. Aspose.Words laat jou toe om twee verskillende tipes Mail Merge operasies uit te voer: eenvoudige Mail Merge en Mail Merge met streke.

Die mees algemene voorbeeld van die gebruik van simple Mail Merge is wanneer jy’n dokument vir verskillende kliënte wil stuur deur hul name aan die begin van die dokument in te sluit. Om dit te doen, moet jy samesmeltingsvelde soos First Name en Last Name in jou sjabloon skep, en dit dan invul met data van jou databron. Terwyl die mees algemene voorbeeld van die gebruik van Mail Merge met streke is wanneer jy wil’n dokument wat spesifieke bestellings met die lys van alle items binne elke bestelling sluit stuur. Om dit te doen, sal jy nodig het om saam te smelt streke te skep binne jou sjabloon – eie streek vir elke bestelling, ten einde dit te vul met al die vereiste data vir die items.

Die belangrikste verskil tussen beide samesmelting operasies is dat eenvoudige Mail Merge (sonder streke) herhaal die hele dokument per elke data bron rekord, terwyl Mail Merge met streke herhaal slegs aangewese streke per rekord. Jy kan dink aan’n eenvoudige Mail Merge operasie as’n spesifieke geval van samesmelting met streke waar die enigste streek is die hele dokument.

Die MailMerge klas verteenwoordig’n Mail Merge funksionaliteit. Met sy eienskappe kan u die vereiste gedrag aanpas voordat u’n Mail Merge - bewerking uitvoer.

Eenvoudige Mail Merge Operasie

‘n eenvoudige Mail Merge word gebruik om die Mail Merge velde binne jou sjabloon te vul met die vereiste data van jou databron (enkel tabel verteenwoordiging). So dit is soortgelyk aan die klassieke Mail Merge in Microsoft Word.

U kan een of meer samesmeltingsvelde in u sjabloon byvoeg en dan die eenvoudige Mail Merge - bewerking uitvoer. Dit word aanbeveel om dit te gebruik as u sjabloon geen samesmeltingsgebiede bevat nie.

Die belangrikste beperking van die gebruik van hierdie tipe is dat die hele dokumentinhoud vir elke rekord in die databron herhaal sal word.

Hoe Om’n Eenvoudige Mail Merge Operasie {#how-to-execute-a-simple-mail-merge-operation}Uit Te Voer

Sodra u sjabloon gereed is, kan u die eenvoudige Mail Merge - bewerking begin uitvoer. Aspose.Words laat jou toe om’n eenvoudige Mail Merge operasie uit te voer met verskillende Execute methods wat verskeie data voorwerpe as die databron aanvaar.

Die volgende kode voorbeeld toon hoe om’n eenvoudige Mail Merge operasie uit te voer met behulp van een van die Execute metode:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// Include the code for our template.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create Merge Fields.
builder.insertField(" MERGEFIELD CustomerName ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Item ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Quantity ");

builder.getDocument().save(dataDir + "MailMerge.TestTemplate.docx");

// Fill the fields in the document with user data.
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" },
		new Object[] { "John Doe", "Hawaiian", "2" });

builder.getDocument().save(dataDir + "MailMerge.Simple.docx");

U kan die verskil tussen die dokument sien voordat u simple mail mergeuitvoer:

En na die uitvoering van eenvoudige mail merge:

Hoe Om Verskeie Saamgesmelte Dokumente Te Skep

In Aspose.Words, die standaard Mail Merge operasie vul slegs’n enkele dokument met inhoud van jou data bron. So, jy sal die Mail Merge operasie verskeie kere moet uitvoer om verskeie saamgesmelte dokumente as’n uitset te skep.

Die volgende kode voorbeeld toon hoe om verskeie saamgesmelte dokumente te genereer tydens’n Mail Merge operasie:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
public class ProduceMultipleDocumentsDuringMailMerge {

    private static final String dataDir = Utils.getSharedDataDir(ProduceMultipleDocumentsDuringMailMerge.class) + "MailMerge/";

    public static void main(String[] args) throws Exception {

        produceMultipleDocuments(dataDir, "TestFile.doc");
    }

    public static void produceMultipleDocuments(String dataDir, String srcDoc) throws Exception {
        // Open the database connection.
        ResultSet rs = getData(dataDir, "SELECT * FROM Customers");

        // Open the template document.
        Document doc = new Document(dataDir + srcDoc);

        // A record of how many documents that have been generated so far.
        int counter = 1;

        // Loop though all records in the data source.
        while (rs.next()) {
            // Clone the template instead of loading it from disk (for speed).
            Document dstDoc = (Document) doc.deepClone(true);

            // Extract the data from the current row of the ResultSet into a Hashtable.
            Hashtable dataMap = getRowData(rs);

            // Execute mail merge.
            dstDoc.getMailMerge().execute(keySetToArray(dataMap), dataMap.values().toArray());

            // Save the document.
            dstDoc.save(MessageFormat.format(dataDir + "TestFile Out {0}.doc", counter++));
            System.out.println("Counter : ");
        }
    }

    /**
     * Creates a Hashtable from the name and value of each column in the current
     * row of the ResultSet.
     */
    public static Hashtable getRowData(ResultSet rs) throws Exception {
        ResultSetMetaData metaData = rs.getMetaData();
        Hashtable values = new Hashtable();

        for (int i = 1; i <= metaData.getColumnCount(); i++) {
            values.put(metaData.getColumnName(i), rs.getObject(i));
        }

        return values;
    }

    /**
     * Utility function that returns the keys of a Hashtable as an array of
     * Strings.
     */
    public static String[] keySetToArray(Hashtable table) {
        return (String[]) table.keySet().toArray(new String[table.size()]);
    }

    /**
     * Utility function that creates a connection to the Database.
     */
    public static ResultSet getData(String dataDir, String query) throws Exception {

        Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");
        String connectionString = "jdbc:ucanaccess://" + dataDir + "Customers.mdb";

        // DSN-less DB connection.
        Connection connection = DriverManager.getConnection(connectionString);

        Statement statement = connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);

        return statement.executeQuery(query);
    }
}

U kan die voorbeeldlêer van hierdie voorbeeld aflaai van Aspose.Words GitHub.

Mail Merge Met Streke

U kan verskillende streke in u sjabloon skep om spesiale gebiede te hê wat u eenvoudig met u data kan vul. Gebruik die Mail Merge met streke as u tabelle wil invoeg, rye met herhalende data om u dokumente dinamies te laat groei deur die streke binne u sjabloon te spesifiseer.

Jy kan geneste (kind) streke skep sowel as saamvoeg streke. Die grootste voordeel van die gebruik van hierdie tipe is om dele binne’n dokument dinamies te verhoog. Sien meer besonderhede in die volgende artikel “Nested Mail Merge with Regions”.

Inligting oor’n Mail Merge streek kan verkry word deur die MailMergeRegionInfo klas te gebruik.

Hoe om Mail Merge Met Streke Uit Te Voer

‘n Mail Merge streek is’n spesifieke deel binne’n dokument wat’n beginpunt en’n eindpunt het. Beide punte word voorgestel as Mail Merge velde wat spesifieke name “TableStart:XXX” en “TableEnd:XXX” het. Alle inhoud wat in’n Mail Merge streek ingesluit is, sal outomaties herhaal word vir elke rekord in die databron.

Aspose.Words laat jou toe om Mail Merge uit te voer met streke wat verskillende Execute methods gebruik wat verskillende data-voorwerpe as die databron aanvaar.

As’n eerste stap, moet ons die DataSet te skep om dit later as’n insette parameter om die ExecuteWithRegions metode:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
private static DataSet CreateDataSet() {
	// Create the customers table.
	DataTable tableCustomers = new DataTable("Customers");
	tableCustomers.getColumns().add("CustomerID");
	tableCustomers.getColumns().add("CustomerName");
	tableCustomers.getRows().add(new Object[] { 1, "John Doe" });
	tableCustomers.getRows().add(new Object[] { 2, "Jane Doe" });

	// Create the orders table.
	DataTable tableOrders = new DataTable("Orders");
	tableOrders.getColumns().add("CustomerID");
	tableOrders.getColumns().add("ItemName");
	tableOrders.getColumns().add("Quantity");
	tableOrders.getRows().add(new Object[] { 1, "Hawaiian", 2 });
	tableOrders.getRows().add(new Object[] { 2, "Pepperoni", 1 });
	tableOrders.getRows().add(new Object[] { 2, "Chicago", 1 });

	// Add both tables to a data set.
	DataSet dataSet = new DataSet();
	dataSet.getTables().add(tableCustomers);
	dataSet.getTables().add(tableOrders);

	// The "CustomerID" column, also the primary key of the customers table is the
	// foreign key for the Orders table.
	dataSet.getRelations().add(tableCustomers.getColumns().get("CustomerID"),
			tableOrders.getColumns().get("CustomerID"));

	return dataSet;
}

Die volgende kode voorbeeld toon hoe om Mail Merge uit te voer met streke met behulp van die ExecuteWithRegions(DataSet) metode:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// For complete examples and data files, please go to
// https://github.com/aspose-words/Aspose.Words-for-java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The start point of mail merge with regions the dataset.
builder.insertField(" MERGEFIELD TableStart:Customers");
// Data from rows of the "CustomerName" column of the "Customers" table will go
// in this MERGEFIELD.
builder.write("Orders for ");
builder.insertField(" MERGEFIELD CustomerName");
builder.write(":");

// Create column headers
builder.startTable();
builder.insertCell();
builder.write("Item");
builder.insertCell();
builder.write("Quantity");
builder.endRow();

// We have a second data table called "Orders", which has a many-to-one
// relationship with "Customers"
// picking up rows with the same CustomerID value.
builder.insertCell();
builder.insertField(" MERGEFIELD TableStart:Orders");
builder.insertField(" MERGEFIELD ItemName");
builder.insertCell();
builder.insertField(" MERGEFIELD Quantity");
builder.insertField(" MERGEFIELD TableEnd:Orders");
builder.endTable();

// The end point of mail merge with regions.
builder.insertField(" MERGEFIELD TableEnd:Customers");

// Pass our dataset to perform mail merge with regions.
DataSet customersAndOrders = CreateDataSet();
doc.getMailMerge().executeWithRegions(customersAndOrders);

// Save the result
doc.save(dataDir + "MailMerge.ExecuteWithRegions.docx");

U kan die verskil tussen die dokument sien voordat u Mail Merge met streke uitvoer:

En na die uitvoering van Mail Merge met streke:

Beperkings van Mail Merge met Streke

Daar is’n paar belangrike punte wat jy moet oorweeg wanneer die uitvoering van’n Mail Merge met streke:

• Die beginpunt TableStart:Orders en die eindpunt TableEnd:Orders moet albei in dieselfde ry of sel wees. Byvoorbeeld, as jy’n samesmelting streek begin in’n sel van’n tabel, moet jy die samesmelting streek eindig in dieselfde ry as die eerste sel.
• Die merge veld naam moet ooreenstem met die kolom se naam in jou DataTable. Tensy u gekarteerde velde gespesifiseer het, sal die Mail Merge met streke nie suksesvol wees vir enige samesmeltingsveld wat’n ander naam as die kolom se naam het nie.

As een van hierdie reëls oortree word, sal jy onverwagte resultate kry of’n uitsondering kan gegooi word.

As jy nie Mail Merge streke gebruik nie, sal dit soortgelyk wees aan die Microsoft Word mail merge, en die hele dokumentinhoud sal herhaal word vir elke rekord in die databron.