BookBuilder

The buildbookheadline method call self.buildpageheadline(page) for every page in the current document.

The buildbookpagination method call self.paginagepage(page) for every page in the current document.

The buildbookversionline method builds an optional version line on every page of the book, including the code. The method calls self.buildpageversionline to do the actual drawing.

The buildchapter method get all the groups from the book. Start at a new page for every group. Skip the group if there are no text modules, it could be a group with image only, as e.g. for the cover page. If the chapter is not showing, then ignore it.

The buildchapters method builds the chapters. Each chapter a new page is started.

The buildchaptertitle method shows the title of the chapter as 'h1' tag if it is not shown already. The reference to the running title is in self.bookbuilder_currenttitle.

The buildcomposition method is the main part of the application. The method gets the preferred filling method from the document style definition. It then decides on the selected strategy to compose the pages. The composing types available are [self.COMPOSELINEAIRFILL, self.COMPOSEPROOFS]. The page file type is the result of the page.getcomposingtype() call. The name of the filling routine is called as method with the page and galley as attributes. This way inheriting applications can define their own composing methods without changing the original code from self. The filling method is called with the elements content tree.

The buildcoverpage method builds the cover page of the document from the book element tree or the chapters list supplied. This method is to be implemented by the inheriting application if a cover page is required. The default behaviour is to do nothing.

The builderrorinfopage method build a new page showing the current error information about the state of the proof and the imagegroup.

The expose method creates the canvas, calls self.expose() and closes the canvas file. The document is the document galley node tree.
The width and height of the document are taken from the first page. If the version attribut is defined, then add the version number to the filename.
The background color of the document is the result of self.getdocument().getbackgroundcolor(). The author of the document is the result of self.getdocument().getauthor().

The buildfinal allows to make final adjustments to the composed book. This method can be redefined by the inheriting application class. The default behaviour is to do nothing.

The buildgroup method will call the method self.buildgrouppage(proof, imagegroup) until all proof text and images from imagegroup are place on a page. Initially to every iteration of the loop, it is checked if a self.EVENT_NEWPAGE request event was posted somewhere in one of the previous placements.
As a safe guard (just in case something does not place any of the proof text or images) there is a loopindex check. If nothing seem to change to the text and images after a placement call and the index runs out of “loop budget”, error pages are built containing the remaining proof text and images.

The buildgrouperrorpage method is called when the placement loop exceeds loop budget when nothing is placed.

The buildgrouppage method tries to place as much of proof text and optional imagegroup on the page. The page may not be empty. It is the task of the method to find the best of possible strategy to follow.

• Everything can fit on the current page: all text and the images can be scaled within their allowed range of proportions.
• If not all text fits on the page and there are no images, fill the page with texts and continue to place the remaining text on the next page.
• If not all text fits on the page or not all images fot on the page, split the text in half and split the amount of images in half and try to fit the halves on the first page. If that still does not work, fit the first half in two quarters and repeat the trategy recursively.
• If either a marker in the proof or an image in the group requires a new page, then this is poted as event request and the rest of the proof and imagegroup is answered.

In order to find out which strategy fits best, the method tries them in simulation mode. The criterium for “best” is the strategy that accommodates most of the proof text and the imagegroup in the smallest amount of pages. The simulation only work within the page, so we cannot backtrack as soon as we create a new page. This means that the method has to be sure about the right strategy on the experience of the filling of one page. By doing this recursively by calling the method for a next page with a reduced amount of text and images, the problem scales down to guessing the best layout for one page, while it is allowed to leave text and images for the next page to solve.

The buildpageheadline method adds the headline to the page using the position from self.getheadlineposition() style value of the page and the style named self.STYLEPAGEHEADLINE. If the page position is None, then don't show the page number.

The buildpageitems method builds the (semi-)fixed elements for a page. The proof is the current slice of proof that will be composed on the current page. Using the existing galley parents of the elements of the proof, it is possible to find the changing information on a page headline if needed. The method will call methods building the several default components that are part of a page such as self.buildbookpagination, self.buildbookheadline. These called methods need to be implemented by the inheriting application class.

The buildpagepagination method adds the page number to the page using the position from self.getpagenumberposition() style value of the page and the style named self.STYLEPAGENUMBER. If the page position is None, then don't show the page number.

The buildpageversionline method draws the incremental version of the book small on side of the page.

The buildpdfdocument tag builds the PDF document, directly called from build if the authorization is checked it calls respectively self.getbookcontent(), self.buildcomposition() and self.buildfile().

The buildspecials method allows to build the special content of pages that are already generated. The information that is stored on the handlespecials call be used here. This method is to be refined by the inheriting application class. The default behaviour is to do nothing.

The buildtableofcontent method builds the table of content of the book, running through all pages to see where the specific head tags are located.
Find the page to build the toc on. The page is answered by self.gettocpage. The method uses the title 'h1' head of the table of content. To be redefined by the inheriting application class. The default behaviour is to answer 'Inhoud' for self.language == 'nl' or 'Table of content' for self.language == 'en'.

The clearevent method clears the event from the pending evens dictionary.

The clearevents clears all events dictionary, e.g. after generating a new page.
This may change in the future in case we need other events than just the new page.

The composelineairfill method implements a lineair page filling composition, equivalent to a text processor with the addition of multiple columns and floating elements that are placed at the side if the running text column.
The method calls a set of methods to generate aspects of the book: self.buildcoverpage(book, chapters) to build the cover page of the book, self.buildchapters(book, chapters) to build all the chapter pages, self.buildpageitems(book) to build all addition items on the pages, such as running headers and page numbers, self.buildtableofcontent(book) to build the table of content on a reserved area on the toc page. Then the self.buildspecials(book) is called to build that information (often on existing pages) that was collected by self.handlespecials. Finally the self.buildfinal(book) is called to wrap up the compostion phase.

The composeproofs method implements a testing composer that shows the generated proofs on singles pages, only by slicing on the natural page boundaries. The images a shown in a fixed width and sorted only by relevance on the right side of the column that they belong to.

The dispatchdocumenttype method decides from available form parameters what type of document is requested. Currently it always will call the standard buildpdfdocument method.

The dispatchplacement method runs through the set of available placement strategies to find one that fits the specified proof and imagegroup. If the execution of one of the strategies answers results, then stop the search and result.

The expose method calls the buildfile method to create the file or files. If pagina is True then create a new file for every page.
The document is the document galley node tree.
If the version attribut is defined, then add the version number to the filename.
During the exposing a temporay file is generated, so if there already was a file, it is not replaced if the exposing does raise an error. After a file was succesfully generated, the original file is replaced by the new one.

The findsliceindex method answers an integer index where the proof should be sliced. This method can be redefined by an inheriting application class. The default behaviour of the method is to check on the index of (height and node.y + node.get(self.STYLESLICEABLE) > height) or node.ismarker(). This assures that if heightis 0, the full height of the proof will be examined to test on markers. Also answer the reason of the slice.

The getactivityname method answers the name of the recursive table that is the source for the element tree. The default behaviour is to answer self.ACTIVITY.

The getanchorrecord tag answers the current anchor record for the specified mode as read and stored by the self.readanchorrecords().
The optional readonly attribute is available to direct the status of the record. Default value is True.
If readanchortrecords has not been called at this point, then do that first.
The method answers a NoneRecord if the mode does not exist in the self.anchorrecords dictionary.

The getbookcontent method answers an element tree, holding the content of the book. Default behaviour is to answer an elementtree from the anchor record (if self.DATABASE is defined. Otherwise a warning is issued that the method should be if self.getdatabasename() does come with no result. If the database is defined, then create an XmlBuilder instance and call self.buildxmlcontent to collect the XML source of the book. Answer the resulting XML.

The getbooktitle method finds the title of the book. If it cannot be found, then answer self.UNTITLED.

The getcaptionproof method answers the caption proof if the caption element is available as image.caption. The style self.STYLECAPTIONNAME is used, with optional width as caption width. If the caption is empty then answer None

The getdatabasename method does return name of the SQL database as defined in self.DATABASE. This method needs ony to be redefined by the inheriting application class if the database is conditional. Default value is self.DATABASE.

The getdocument method answers the running document.

The getdocumentname method answers the name of the document, both for use in the PDF document and filename.

The getdocumenttype method answers the type of document to be generated. The default behaviour is to answer self.DOCUMENTTYPE.

The getfilename method answers the file name of the PDF document to save, without the extension. All whitespace is stripped from the name and the name is all lower case.

The getfilepath method answers the relative filepath for the PDF document without extension. The default behaviour is to answer '_downloads/' + self.getfilename().

The getfilltype method answers the fill type of the page. If the page attribute is None then answer the fille type of the document.

The getheadline method answers the headline of the page Default behaviour is to show the headline centered on the top of the page. This method can be redefined by the the inheriting application class if an alternative behaviour is required. The appication can store information in the page that can be used to build that actual page dependent headline.

The getheadlineposition method answers the (x, y, align) tuple of the position of the headline on the page. The align value is one of [self.ADJUSTLEFT, self.ADJUSTRIGHT, self.ADJUSTCENTER] to indicate the alignment of the headline on this page. The calling method needs to adjust the position relatively since we don't know that style and length of the headline here.
If the headline should not be shown on the page, then answer None. Default behaviour is to show the headline centered on the top of the page. This method can be redefined by the the inheriting application class if an alternative behaviour is required.

The getimageproof method first creates a GalleyImage node instance. We have to do this separate from the automatic galleybuilder.image option, since we want to be able to change the size (depending on the size of the caption). Then create a GalleyBuidler instance and append the image and the caption if it exists. For the image the style or self.STYLEIMAGENAME is used.

The getnextpagenumber method answers the pagenumber of the page or the next page to be created. The default behaviour is to answer the last page of the document, incremented by one. If there are no pages yet, the answer the result of self.get(self.STYLEFIRSTPAGENUMBER).

The getpagenumberposition method answers the (x, y, align) tuple of the position of the pagenumber on the page. The align value is one of [self.ADJUSTLEFT, self.ADJUSTRIGHT, self.ADJUSTCENTER] to indicate the alignment of the page number on this page. The calling method needs to adjust the position relatively since we don't know that style of the page number here.
If the pagenumber should not be shown on the page, then answer None. Default behaviour is to show the pagenumber centered on the bottom of the page. This method can be redefined by the the inheriting application class if an alternative behaviour is required.

The getplacementstrategies method answers the ordered list of placement strategies self._placementstrategies as initialized by self.initalizeplacementstrategies in the constructor of the BookBuilder class. This behaviour can be redefined by the implementing application class.

The gettableofcontent method collects the table of content from the current set of self.pages from the optional first until (including) last page index. The default behaviour is to build the table of content for all pages.
The method uses page.getelementsbyorder() to get a list of chronological placed elements from the page (the page.getelements() reads from the composer dictionary which does not ansers the elements in chronological order of placement. If the <h1> is placed as separate element, it may not be return before the placed of an element that includes <h2>.
The build is only performed on “placed” composer elements, not on the fixed elements of the page and only if their style names are in the tags list. The result of the method is a “toc” tagged XML document.
Keep track of the current title and page number when running through the tree to avoid duplication is a chapter title runs over several pages.
Note that the only tags can be found that have a named style. It should be possible to retrieve the name of the tag in the node style by style.get(self.STYLENAME).

The gettocpage method answers the toc page as stored in self.bookbuilder_toc_space by self.settocpage.

The gettocpages method answers a list of pages that the toc should be made from. The default behaviour is to ansers all numbered pages starting after the toc page.

The gettoctags method answers a list of that tag/style names that the toc builder should search for in the composed book. This method can be redefined by the inheriting application class. The default behaviour is to answer ['h1', 'h2'].

The gettoctitle method answers the title of the table of content in the right language. This method can be redefined by the inheriting application class. The default behaviour is to answer the string 'Table of content'.

The gettocxml method answers the constructed XML of the table of content. The self.gettocpages method is called to get a list of pages that need to be examined by the toc builder.
The self.gettableofcontent method is called to build the xml of the toc content.

The getversion method answers the version number of the document. This method needs can be redefined by the inheriting application class. The default behaviour is to answer the result of e.form['version'].

The handlespecials method takes care of modules that needs special treatment for placement of layout, such as table of content, legend, colophon and footnotes. This method is to be redefined by the inheriting application class. The default behaviour is to do nothing and to answer False, indicating the calling methods that nothing special was done with modules. The page, chapter and documents attributes are also avaiable here, in case the application class needs them for information.

The hasevent method answers True if the event queue contains event.

The initalizeplacementstrategies method initializes and answers the ordered list of methods that take the attributes page, proof, imagegroup, imagehints and freevolume. A strategy method has to be able to detect if the strategy applies and then take action. Then a tuple of (proofstatus, remainingproof, imagestatus, remainingimagegroup) is answered, where the proofstatus and imagestatus are one of (self.PLACEMENT_PLACED, self.PLACEMENT_NOTPLACED, self.PLACEMENT_EMPTY) defining the status if the placement (the strategy method did think it applied but when trying decided that it could not place anything). The remaining proof content (original or slice) and the remaining images (original or slice) are ansered too.
If the strategy method does not apply, then it should answer None. By default the following strategies are implemented in ordered list of strategies: (placementproofonly, placementimageonly, placementproofnotsliced, placementimageandsmallproof, placementfitttotalvolume, placementmoreimagethantext, placementmoretextthanimage, placementdefault).

The initializechaptervalues method is called when a new chapter starts, to allow self initialize the running values for the new chapter. This can be used to ignore identical headnings in multiple placed elements.
This method can be redefined by the inheriting application class. The defauilt behaviour is to do nothing.

The initializepagevalues method is called when a new page is created, to allow self initialize the running values for the new page. This can be used to ignore identical headings in multiple placed elements.
The method can be redefined by the inheriting application class. The default behaviour is to do nothing.

The newdocument method answers a new GalleyDocument instance. The optional style attribute defines the initial style of the document. Default style used is the result of self.getcascadedstyle().

The newelement method answers an instance of Element holding record as data. This method can be redefined by the inheriting application class if a more specific element class is required with better knowledge about the information of the record tree. The optional where attribute defines the selection of the records when the element will read the child elements. The optional order attribute defines the sorting order of the records when the element will read the child elements.

The newgalley method answers a Galley instance, generated with the defined xml content and the style. The style instance can be a name string of an existing style or a Style instance. The method sets the cursor x position to the sum of the style values self.STYLEINDENT and self.STYLEFIRSTINDENT.

The newgalleybuilder method answers a new galley builder instance. The default behaviour is to use the GalleyBuilder class. This may be redefined by the inheriting application class that needs an inheriting galley builder with adjusted behaviour.

An image group holds a group of images (technically all instances of Element) the must have a visual relation with each other in a layout and with a proof.
An image group has knowledge about the behaviour, ratio and minimum and maximum sizes of the images it holds. So it can be used guess the fittin the group in a composition. The newimagegroup method by default answers a new ImageGroup instance. If the image group needs different or additional behaviour, this method can be redefined by the inheriting application class to answer another kind of image group instance.

The newpage method generates a new page based on the optional style attribute or the current style. The chapter attribute is the current running chapter that is avaible when constructing the headline for this page.

The newproof method answers a Proof instance that comes from a generated “mini” Galley, generated with the defined xml content and the style. The style instance can be a name string of an existing style or a Style instance.

The notify method show the progress of the composing and exposing. The default behaviour is to print an initial line to show the book name that is currently under construction. This method can be redefined by the inheriting application class.

The placecolumn method takes a proof instance and performs an initial split to get an initial guess about the height of the slice to be placed. There can be several reasons why this slice is performed. The self.slice() method used answers the reason for slicing. The calling method can decide what to do with it then. If the reason is self.EVENT_NEWPAGE then answer this with the proof reduced by that node that caused the newpage split. Otherwise the method tries to place as much of the slice as it can in the defined height on the page. The optional placement attribute indicates the preferred search direction for free space in the composer. The value is one of Composer.VERTICAL, Composer.HORIZONTAL, Composer.AREA, Composer.SQUARE]. If the proof is longer than the available space found by the page composer, then “placeable slice” is sliced again to place as much as fits and answer the remainingproof as a new proof. Also answer the status self.PLACEMENT_NOTPLACED
If all of height of the proof could be placed then answer None. If nothing of the proof instance could be placed then answer status self.PLACEMENT_PLACED
The page attribute can be None. This happend on the inital call of this method when composing a document. We assume that the proof starts with a newpage group.
If the addhot attribute is set to True (default is False), then try to add the proof to the current hot element in the page composer.

The placeimage method does place an image on a free position on the page. If there is a caption with the image, then make a proof first. If the caption proof has a height of only one leading, then reduce the image height. Otherwise just add the caption. The method answeres a boolean flag if it was placed or not. This allows the calling application to decide on placing the image in a smaller scale. The answering flag tells if the image was placeable in the requested size.
The optional placement attribute defines the searching strategy the next available empty space in the composer that would accommodate the image. The default value for the placement is Composer.RELEVANCE, which selects from the list of defined hotspots. Other search strategies are Composer.MAGNETIC, Composer.VERTICAL and Composer.HORIZONTAL. For the hotspots of the Composer.RELEVANCE the table in self.get(self.STYLEIMAGEHOTSPOTS) is used.

The placeimages method tries to place as much as possible of the images in imagegroup. on the page. In order to know how much of them fit on the given page (which may not be empty as we get in) and how much the images should be reduced in order to make them fit, some iterations are made by calling self.placesizedimages with the page in simulation mode. The result of the method is a tuple that contains respectively a new imagegroup that could not be placed, an indicator about the placement (one of [self.PLACEMENT_PLACED, self.PLACEMENT_NOTPLACED] and an indicator about the need for a new page following the placements in this method (one of [None, self.EVENT_NEWPAGE].
Placing images is a complicated process that can hardly be worked through without simulation and backtracking. There are several independent parameters that have a part in the fitting in the free space on the page:

• the volume of text, already placed on the page, resulting in a fragmentation and limitation of the available free space;
• the number of images to be placed;
• the ratio of width and height for every individual image;
• the preferred range of sizes that each individual image can be used in;
• image may have been flagged as unscaleable;
• the order of the images
• the existence and volume of captions that will change the ration of the image-caption combination if the image reduces in side, given the fact that the caption pointsize and leading is fixed.

The target page, with its current state (which may already be simulating or not) is put into simulation mode to find what the best composition if for the given set of images. The method runs through a number of simulations, while manimupulating the variables, until a setting is found that fills the needs. Then the page is told to keep this simulation as the main composer state and forget about the others. If no solution was found, then the original composer state is restored.
The method does finish by answering the remaining images and values about the status of the operation.
If the optional forcedsize attribute is set to (maxsize, minsize) then all images are forced to that size. This attribute is mainly for debug usage to make all images appear on the page.

The placementbetterallonnewpage method considers situations that better could start on a new page.

• where only a small portion of the defined proof and imagegroup content can be placed on the current page, while none of the images can be placed and all would fit on a new page.

Default placement, first proof, then images. In principle this should never happen, since it means that the none of the defined strategies actually worked.
Answer a tuple of format (proofstatus, remainingproof, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If the total volume of text and images fits the page then place it all. Answer a tuple of format (proofstatus, remainingproof, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If there are images and just a tiny piece of text, place the text first, avoiding it goes to the next page. This make XSL images shrink a bit to accommodate the litle remainder. Answer a tuple of format (proofstatus, remainingproof, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If there are just images to place, don't try to place the proof. Answer a tuple of format (self.PLACEMENT_EMPTY, None, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If the total volume does not fit and there is more text than images, place the text first and then see how far we get with the images. Answer a tuple of format (proofstatus, remainingproof, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If the total volume does not fit and there is more text than images, place the text first and then see how far we get with the images. Answer a tuple of format (proofstatus, remainingproof, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If the proof is not sliced (original one), then always place the text first. Answer a tuple of format (proofstatus, remainingproof, imagestatus, remainingimagegroup).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

If there is just a proof to place, don't try to place any images. Answer a tuple of format (proofstatus, remainingproof, self.PLACEMENT_EMPTY, None).
Otherwise, if the proof and imagegroup do not fit the pattern, answer None, which indicates the calling application to try another strategy.

The placesizedimages method tries to place the images on the page from the list of scaledimagelist attribute that has the layout ((image, (width, height)),...). Although the supplied set is scaled based on the volume of free space of the page, it does not mean that the images really are going to fit. The uncertain factor is the individual ratio of each image and the amount of fragmentation of the page free volume. If no space is left, then answer a list of the remaining images, that could not be splaced.
Images that answer False to the call image.isresizeable() got the maximum size for all constraint values in the scaledimagelist.

The postevent method adds an event to the pending eventlist. This allows various level in the application to post e.g. the request for a new page event. The event storage acts like a FIFO (First In Fist Out) register.

The printerrorinfo method prints the current error information about the state of the proof and the imagegroup.

The readanchorrecords tag does read and store the main record for the current session. In case getanchorrecord is code in an earlier stage, then the call to readanchorrecords is executed there.
The optional readonly attribute is available to direct the status of the record. Default value is True.
To be redefined by the inheriting application class. The default behaviour is to create an application attribute anchorrecord holding a NoneRecord instance.

The reservetitlespace method allows the inheriting application to reserve the space that was used for the title by redefining the method. The default behaviour is to do nothing.

The reservetocspace method allows the inheriting application to reserve space after the toc is written by redefining this method. This method can be redefined by the inheriting application class. The default behaviour is to do nothing.

The setdocument method stores the running document.

The settocpage method stores the page in self.bookbuilder_toc_space to be retrieved and answered by self.gettocpage.

The slice method slices the proof into two parts where in the index that is the result of self.findsliceindex(proof, width, height). The two resulting Proof instances adjust the position and size of their nodes so that the top node is always on position node.y = 0 and their width and height attribites match with their new content. Additionally answer the status of the slice (the reason why it got sliced there).
The proof content is always sorted on the node.y value.

The typesetmodules method converts the sequential list of modules to xml and then does the typesetting. The resulting Proof is answered.

The unreservetocspace method allows the inheriting application to unreserve space that the toc must be built on. This method can be redefined by the inheriting application class. The default behaviour is to do nothing.