PlanetPress for work: Multiple overflows in a single document
Originally published at: http://planetpresstips.wordpress.com/
The post below was taken from my personal “PlanetPress Tips & Tricks” blog which is – or rather, was, considering the lack of recent updates! – both an outlet for my creative writing skills as well as a good method of getting specific tips and tricks to fellow users on the forums. I chose this specific tip because in my tech support days, it answers a question that, though not frequently asked, was both useful to know and helped out a couple of clients.
Today I will show you that it’s possible to display more than one overflow on a single PlanetPress document, even if there are multiple pages around it and even if both overflows are on the same page.
The data file
Let’s go ahead with an example that is very common: an invoice with a variable number of items. Consider the following: You have a job file that comes in as a text-only file. The first 10 lines are the header data (client’s address, account number, sales rep, etc). The following lines (anywhere between 1 and 75) are the items that are invoiced to the client. There’s 2 total lines, then you have up to 10 lines of “notes”, which generally consist of additional information, instructions, or notes to the client. To make our life easier, there’s no data to grab in the end and each line of the notes starts with a pound sign (#).
It would be possible of course to create a simple repeat that starts on line 11 until 113, which would list all the items and then the notes, but in our case, we want them separated because that is the way the document is designed (or that’s how the boss wants it, and that’s that!). Obviously, two data selection objects will be needed to achieve this. Both objects will actually be the same data selection (that is, they will look in the same place) but will have different options applied to them.
Creating your data selections
To start, you create your first data selection, which will consist of reading a single complete line (11). Then, in the Repeat section, enter From line 11, To line 86, for a total of 75 lines. The repeat is vertical only, 1 iteration per row/column. The first bit of magic comes from the Iteration Condition, which controls whether or not a line will appear using a PlanetPress Talk condition. In this case, the condition is fairly straightforward: =ne(@(¤t.line, 1,1), ‘#’) . This makes the line appear if the first character is not the pound sign, which is our line repeats. We’ll include the totals in the line repeat, but it would be possible to treat them separately if that was necessary.
Now for the overflow of that object, say we want to display up to 25 lines per page, then the condition to overflow and exit would become =&iterationcount >= 25 , which I hope is self-explanatory at this point.
The second data selection is almost the same, with some slight difference. First, the condition would be the contrary, e.g. =eq(@(¤t.line, 1,1), ‘#’) , and the condition to overflow and exit would be =&iterationcount >= 5 if we want a maximum of 5 lines of notes per page. I realize this probably doesn’t reflect real documents, that’s the disadvantage of not preparing a real data file and document before writing this post!
Creating the correct conditions
The second bit of magic comes here: as it is now, if you were to use this document you would end up with both overflows running at the same time and conflicting with each other, leading to pretty unexpected results (what results exactly I can’t tell you, since they’re unexpected!). To resolve this we need to apply proper conditions to the pages that we don’t want to repeat, as well as to the two data selections we just created. The way we do this is by using the boolean (true or false) variable called ¤t.overflowing . This variable is specifically used for overflowing documents and has the following values depending on where it is in the processing of your document:
- Until it arrives at the first overflowing object, the value is always False.
- When it exits the overflowing object, if there is an overflow (in other words if the condition to exit and overflow is true), it becomes True.
- It stays to True until it gets to the end of all the pages, and then from the beginning of the document until it hits the overflowing object again.
- The overflowing object that started the overflow will always ignore its value – that is, it will always run until it finishes every repeat it has.
- When it exits the last overflow (or if there is no overflow to begin with), it becomes False.
In other words, ¤t.overflowing is always true between iterations of any one overflowing object. This is precisely why having two overflowing objects is a problem: there is only one set of overflowing variables and both objects can modify them.
The ¤t.overflowing can thus be applied like so:
- On any page that does not contain an overflowing object, apply the following condition: =¤t.overflowing = False .
- On each of your overflowing objects, apply the same condition.
If you’ve followed my train of thought (and I agree that I may be hard to follow), you may guess how the document would now react. The first pages execute correctly. The first overflowing object causes that specific page to repeat as many times as it takes to print all the data (in this case, a maximum of 3), and does not print the second overflowing object since its conditions is false. When it exits the last loop, then the second repeating object does the loop again (this time only once or twice), repeating only that specific page excluding the first overflowing object. Then when that second loop exits, it runs the last pages of the document.
The document I describe here could potentially print from 3 to 7 pages depending on the data available.
I haven’t described all the variables used, so I invite you to take a look at the following page that describes some of what I’ve said here today: http://help.objectiflune.com/en/planetpress-design-user-guide/Default_CSH.html#/1490.html
The line repeat page also has some information on repeating objects: