Ability to apply XSL style sheet to Template

[ghost]

Sometimes we need to perform more complex actions with document template than just simple replace of ${} parameters. XSLT really helps in such situations.

This issue is a proposal of the correspondent class method implementation with the followed signature.

/**
 * Applies XSL style sheet to XML template.
 *
 * @param DOMDocument &$xslDOMDocument
 * @param array $xslOptions = array()
 * @param string $xslOptionsURI = ''
 */
public function applyXslStyleSheet(&$xslDOMDocument, $xslOptions = array(), $xslOptionsURI = '')
{
    ...
}

Assumption: we have XSL style sheet loaded as DOMDocument before the method call.
Requirement: "php_xml.dll" library.
Limitation: XSLT 1.0, XPath 1.0 (because of XSLTProcessor).

[Progi1984]

Could you have a sample for testing this feature ?

[ghost]

Right now - no. I have something that works, but it can't be used as sample "as is". It requires some time to make a sample from that. You think it's necessary?

[gabrielbull]

We need to add unit tests to new features if we want to achieve a decent test coverage some day.

Here is an example of a unit test I made for the Image Wrapping feature.

https://github.com/PHPOffice/PHPWord/blob/master/test/PHPWord/Tests/ImageTest.php

[ghost]

OK, guys. We'll see what I can do.

Any guides, wishes, and recommendations on the tests are welcome.

[Progi1984]

@RomanSyroeshko The sample is necessary. It permits to test your code easily before integration.

@gavroche Yes tests code are in the pipe for the next version (0.7.1) : #43

[ghost]

Guys, I'm stuck.

AFAIK, samples are just samples. Samples live in "samples" folder, provide users with "how to" and they are not somehow connected with unit tests. On the other hand, unit tests is a different thing. Unit tests live in "test" folder.

Do you want me to add something to the "samples" or to the "test" folder?

[gabrielbull]

@Progi1984 will have the last call on this but if I can had my 2 cents:

Every feature that is added needs to have a unit test with it. The samples should not exist and be replaced by a good documentation. In the last feature I added, I added the documentation directly to the README.md. This is O.K. for small projects but as we make more documentation, we will need to move some documentation elsewhere. A good practice will always be to include a getting started and examples to the README.md because it increases the number of people using the library.

So to answer your question, I guess you could make a unit test and than add a little HOWTO in the README.md for using your feature.

But wait for an answer by @Progi1984 .

[Progi1984]

I'm ok with @gavroche.

In Utopia, a good documentation would replace samples.
Personnally, i see like that :

• a good documentation (in markdown in the directory docs)
• some samples ( a good sample explain a feature )
• units tests with PHPUnit

[gabrielbull]

Why atoum and not PHPUnit? That would imply that developers have to learn a new Unit Test framework instead of using one that they already know.

[Progi1984]

Oops... @gavroche, it's an error of my side, I discussed about atoum and unit tests with my wife while I writed my answer... It's not atoum for this project, but PHPUnit.

[ghost]

Guys, could you please clarify why unit tests are organized in the way they are orginized now?

I would like to suggest using an approach when "test" directory mirrors "Classes" directory (see here for details). On my mind such organization looks more clear.

What do you think?

[Progi1984]

@RomanSyroeshko I wait for @brunocasado (#22) before releasing PHPWord 0.7.0. In the next release (0.7.1), one of my goal is to implement unit tests in all the project (#43). So, at this moment, I will check an eye on all the code and the organization of the code.

[ghost]

Okay, I will wait for 0.7.1 too then. It will be better to write unit tests once for correct organization of code than rewrite them several times.

[Progi1984]

@RomanSyroeshko In the commit of yesterday night, I have moved the unit tests directory and put in place some tests.

[ghost]

Roger that.

[ghost]

@Progi1984, I'm done with that for now. There are 2 negative tests. To create positive test I need API from the PR #57 (issue #56). That PR/issue is planned for 0.7.2. So, please merge the tests "as is". I will create positive test later, in scope of the issue #56.

As regards PR #57 (issue #56), there are two options.
a) To leave it in 0.7.2.
b) To replan it for 0.7.1.
I suggest option b), but it's up to you.

[Progi1984]

I replan them (#56 & #57) to 0.7.1....

[Progi1984]

Merged in develop branch.

[joe-mcpherson]

I would like to use this feature (as it potentially may solve my need?) as the Template Processor can't handle what I need to do, which is beyond simple replacement, but I have no idea how this works?? It's not clear from the tests. An example in the sample code folder would be very useful IMHO

[ghost]

Uhmm, the idea behind this feature is to allow advanced transformations of XML-based documents, more complex than regular string replacement. Think of it like of document structure transformation, not data transformation. For example, my document templates contain table templates. Each table template is represented by a header row and a data row template. So, I used XSL transformation to clone data rows before table population, and to remove unpopulated tables at the end.

The code, which you already found among tests, will help you to understand how to actually call/run this feature. To understand what you can do with it and what you can't you should dive a little into XSL basics, and into your document format. The latter is important, because you can actually run XSL-transformation which will generate you a broken document, and it won't open. So, be careful.

Good luck!

[joe-mcpherson]

Many thanks @syroeshko for your work and that incredibly quick response on this old thread! I'll give it a try, but my XSL knowledge needs some refreshing! For other reading this the test file and XSL files in question I believe are: https://github.com/PHPOffice/PHPWord/blob/develop/tests/PhpWord/TemplateProcessorTest.php
https://github.com/PHPOffice/PHPWord/blob/develop/tests/PhpWord/_files/xsl/remove_tables_by_needle.xsl

[ghost]

Huh, XSL looks quite challenging for me too, each time. Stay strong! 😃 One important note here: use XSLT version 1.0. Those days XSLTProcessor wasn't able to support newer specifications. The same with XPath: stick with version 1.0.

And yes, you found the right test file. Also there is passthrough.xsl, which does nothing useful I believe (it was long time ago ...).