Documentation

Clone content

The goal of this section is to offer you some illustrative examples on how to clone specific content from a template.

The options are manifold. By providing a "needle" (the text to be searched for), you may clone from a template the following blocks of content:

  • bookmark: the contents bookmarked with that needle within the template,
  • paragraph: the paragraphs that contain the needle text are cloned,
  • list: the lists (with all its items) that contain the needle text are cloned,
  • list-item: the list items that contain the needle text are cloned,
  • table: the table that contains the needle text is cloned unless the text fall within a subtable,
  • table-row: the same that for table but just for a table row,
  • image: the images which alt text (title or description) include the needle text are cloned,
  • chart: the charts which alt text (title or description) include the needle text are cloned,
  • textbox: all textbox content of a textbox that contains the needle text is cloned,
  • heading: all the contents that fall under a given heading (including subheadings) are cloned whenever the heading contains the needle text.

By also providing a match we can further filter the elements to be cloned. If a match is provided the needle may be omitted in certain cases.

It is also important to recall that the "cloning of content" is the second set of instructions (just after the removal of any content) to be carried out by Docxpresso when processing the JSON data.

We strongly recommend to use Docxpresso variables as needles. This is so because Word and Libreffice may introduce XML tags that are not visible but may hinder getting the expected result in the search process. Docxpresso variables are parsed to eliminate that issue and you may later delete them or set them to an empty string.

Cloning bookmarked content

The following JSON will clone all content bookmarked under the tag "deleteme":

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "deleteme",
                "element": "bookmark",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Cloning paragraphs from a template

The following JSON will clone all paragraphs (but not headings) that include the words "Clone paragraph":

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "Clone paragraph",
                "element": "paragraph",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

By default the match parameter has been set to 1, i.e. only the first ocurrence is cloned but if would like the second ocurrence to be cloned we will have to change the JSON to:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "Clone paragraph",
                "element": "paragraph",
                "repeat": 1,
                "match": 2
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Cloning lists and list-items from a template

The following JSON will clone the list item that includes the text "Item 1":

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "Item 1",
                "element": "list-item",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

If we want to clone the whole list we only need to change the option element to list:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "Item 1",
                "element": "list",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Cloning tables and table-rows from a template

If we want to clone a particular table row including the text "First" we need to use the following JSON:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "First",
                "element": "table-row",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

In case we want to clone the whole table we have just to modify the element property:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "First",
                "element": "table",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

There may be cases when you want to clone blocks of rows in a way that is not possible with the clone method, for example, when there are vertical merging of table cells. For those cases you can still work them out wit the the help of the replace method applied to tables that allow for the cloning of blocks of rows with simultaneous replacement of variables.

Cloning images from a template

In case we want to clone an image with an alt text ({{my_image}} in this particular case):

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "my_image",
                "element": "image",
                "repeat": 1,
                "container": true
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

We have set the container parameter to true so the cloned image is within its own paragraph. But this, of course, may depend on your particular use case.

We could also have chosen to clone the image because of its order of appearance to get the same result:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "element": "image",
                "match": 1,
                "repeat": 1,
                "container" 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Cloning charts from a template

In case we want to clone a chart with an alt text ({{my_chart}} in this particular case):

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "my_chart",
                "element": "chart",
                "repeat": 1,
                "container": true
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

We could also have chosen to clone the chart because of its order of appearance using the match parameter. We leave that option as an exercise for the reader.

Cloning textboxes from a template

In case we want to clone a textbox including the text "required":

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "required",
                "element": "textbox",
                "repeat": 1,
                "container": true
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Cloning content under a heading

We will clone a heading of level 2 that contains the text "cloned":

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "cloned",
                "element": "heading",
                "heading-level": 2,
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Cloning multiple elements

We can, of course, combine any of the previous:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "clone": [
        {
            "options": {
                "needle": "cloned",
                "element": "heading",
                "heading-level": 2,
                "repeat": 1
            }
        },
        {
            "options": {
                "element": "chart",
                "match": 1,
                "repeat": 1,
                "container": true
            }
        },
        {
            "options": {
                "needle": "Item 1",
                "element": "list-item",
                "repeat": 1
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc