Inclusão de Arquivos

Com a inclusão de arquivos é possível incluir arquivos e elementos XML para partes especificas do douidefinition.xml.

Utiliza-se no local que se deseja importar de outros arquivos o seguinte formato:

<!-- #include(file: "/path/to/included/file.xml", xpath: "/path/to/node/to/be/included", omitParent: true) -->

Ambos os parametros file e xpath são opcionais, mas ao menos um dos dois deve estar presente.

Definição dos parâmetros:

file

Indica qual arquivo será incluído. Caso seja nulo (ou vazio), o arquivo a ser incluído será o arquivo corrente. Esse parâmetro é relativo ao arquivo atual ou absoluto, caso comece com "/".

xpath

Indica o Xpath a ser utilizado para a busca do nó a ser incluído. Caso seja nulo (ou vazio), o arquivo inteiro será incluído. Caso mais de um nó satisfaça a busca, o primeiro nó que satisfaça a busca será utilizado. É importante notar que o nó encontrado (caso haja), será incluído contendo seu próprio texto.

omitParent

Indica se o elemento raiz da inclusão deve ser omitido ou não. Caso seja (valor true), o elemento raiz da inclusão será omitido e somente os nós filhos serão incluídos. Caso contrário (valor false), ele será incluído também.
Caso o parâmetro xpath tenha sido definido, o elemento raiz da inclusão é o primeiro elemento o qual satisfaça o dado xpath. Caso o parâmetro xpath não tenha sido definido, o elemento raiz da inclusão é o elemento do documento.
O valor padrão, caso não seja definido é false.
Esse parâmetro é especialmente útil quando se deseja incluir os nós filhos de um determinado nó e adicionar outros nós irmãos.

A seguir alguns exemplos de uso:

Exemplo 1

Neste exemplo será incluído o conteúdo completo de um arquivo.

Arquivo a ser incluído:

<!-- comentário -->

<rootElement>

    <child type="a">

        <inner>lorem ipsum</inner>

    </child>

    <child type="a">

        <inner>dolor sit amet</inner>

    </child>

</rootElement>

Código de include utilizado:

<!-- #include(file: "/caminho/do/arquivo/incluído.xml") -->

Resultado da inclusão:

<!-- comentário -->

<rootElement>

    <child type="a">

        <inner>lorem ipsum</inner>

    </child>

    <child type="a">

        <inner>dolor sit amet</inner>

    </child>

</rootElement>

Exemplo 2

Neste exemplo será incluído um nó cujo xpath utilizado corresponde a apenas um nó.

Arquivo a ser incluído:

<!-- comentário -->

<rootElement>

    <child type="a">

        <inner>lorem ipsum</inner>

    </child>

    <child type="a">

        <inner>dolor sit amet</inner>

    </child>

</rootElement>

Código de include utilizado:

<!-- #include(file: "/caminho/do/arquivo/incluído.xml", xpath: "/rootElement") -->

Resultado da inclusão:

<rootElement>

    <child type="a">

        <inner>lorem ipsum</inner>

    </child>

    <child type="a">

        <inner>dolor sit amet</inner>

    </child>

</rootElement>

Exemplo 3

Neste exemplo será incluído um nó cujo xpath utilizado corresponde a mais de um nó.

Arquivo a ser incluído:

<!-- comentário -->

<rootElement>

    <child type="a">

        <inner>lorem ipsum</inner>

    </child>

    <child type="a">

        <inner>dolor sit amet</inner>

    </child>

</rootElement>

Código de include utilizado:

<!-- #include(file: "/caminho/do/arquivo/incluído.xml", xpath: "/rootElement/child") -->

Resultado da inclusão:

<child type="a">

    <inner>lorem ipsum</inner>

</child>

Nesse caso, ambos os nós "child" satisfazem a busca, no entanto somente o primeiro nó será incluído.

Exemplo 4

Neste exemplo será incluído um nó presente no próprio arquivo.

Arquivo original:

<interface id="edit">

    <sources>

        <source id="s1">...</source>

        <!-- #include(xpath: "/douiDefinition/interfaces/interface[@id='edit']/sources/source[3]") -->

        <source id="s2">...</source>

        <!-- #include(xpath: "/douiDefinition/interfaces/interface[@id='edit']/sources/source[3]") -->

        <source id="s3">...</source>

    </sources>

</interface>

Resultado da inclusão:

<interface id="edit">

    <sources>

        <source id="s1">...</source>

        <source id="s3">...</source>

        <source id="s2">...</source>

        <source id="s3">...</source>

    </sources>

</interface>

Exemplo 5

Neste exemplo será incluído um nó contendo um #include, o que não é suportado.

Arquivo a ser incluído:

<interface id="edit">

    <sources>

        <source id="s1">...</source>

        <!-- #include(xpath: "/douiDefinition/interfaces/interface[@id='edit']/sources/source[3]") -->

        <source id="s2">...</source>

        <source id="s3">

            <!-- #include(file: "sources.xml", xpath: "/douiDefinition/interfaces/interface[@id='edit']/sources/source[3]") -->

        </source>

    </sources>

</interface>

Neste caso, será exibido um erro, pois ao tentar incluir o elemento <source id="s3"> é detectado um segundo <!-- #include(...) -->, o que não é permitido.

Exemplo 6

Neste exemplo será incluído um nó omitindo o nó raiz.

Arquivo original:

<interface id="add">

    <sources>

        <source id="s1">...</source>

        <source id="s2">...</source>

        <source id="s3">...</source>

    </sources>

</interface>

<interface id="edit">

    <sources>

        <!-- #include(xpath: "/douiDefinition/interfaces/interface[@id='add']/sources", omitParent: true) -->

        <source id="s4">...</source>

    </sources>

</interface>

Resultado da inclusão:

<interface id="add">

    <sources>

        <source id="s1">...</source>

        <source id="s2">...</source>

        <source id="s3">...</source>

    </sources>

</interface>

<interface id="edit">

    <sources>

        <source id="s1">...</source>

        <source id="s2">...</source>

        <source id="s3">...</source>

        <source id="s4">...</source>

    </sources>

</interface>