GitHub user bengbengbalabalabeng created a discussion: [DISCUSS] Discussion on the capability boundaries and facade API style of the new module fesod-doc
## Background Source: https://lists.apache.org/thread/y67yzt1bhbrxq61m9hhlgg1ook45h6yw Word document processing is an extremely high-frequency requirement in report generation, document creation, and data export. To ensure that the new `fesod-doc` module continues the excellent development experience, I would like to first discuss the capability boundaries and facade API style of this module. ## Capability boundaries and format support 1. Format support (`.docx`/`.doc`) It is recommended to focus solely on `.docx` for now (as the `OOXML` format has a natural advantage in node positioning for template filling) to keep the module lightweight and modern. 2. Read/Write priority It is recommended to prioritize support for "**template filling** and custom writing" (as this covers the vast majority of common scenarios), while structured reading and parsing can be left for later gradual implementation. ## Facade API style I have envisioned the following API styles: 1. A fully fluent-style API ```java // for custom writing FesodDoc.write(pathname) // global configure .configure(spec -> { spec.page(p -> p.size(A4)) .header(h -> h.text("this is header")) .footer(f -> f.text("this is footer").pagination(...)) .style(s -> s.fontSize(24)) }) // paragraph configure // or .paragraph("Title", DocStyles.STYLE_TITLE) // or .paragraph("Heading 1", DocStyles.STYLE_HEADING_1) // or .paragraph("content. Use the global default style") .paragraph("Title", s -> s.bold().fontSize(24).align(CENTER)) .paragraph(spec -> { spec.text("This is content.", s -> s.fontSize(16)).break() .image(image_pathname, s -> s.size(width, height)) .links("https://fesod.apache.org";) }) // inline-table configure .table(TableModel.class, List<TableModel>) .table(table -> { table.head(HeadBuilder.forSimple("ID", "Name")) .body(List<?>) }) .doWrite(); @DocTableHeadStyle(...) @DocTableContentStyle(...) public class TableModel { @DocTableProperty("ID") private Integer id; @DocTableProperty("Name") private String name; // Getter & Setter } // template filling FesodDoc.write(pathname, TemplateModel.class) .withTemplate(template_pathname) .configure(spec -> { // placeholder: My name is {{name}}. spec.startDelimiter("{{").endDelimiter("}}") // or // .templateRenderer(TemplateRenderer) }) .registerRenderPolicy(RenderPolicy) .registerConverter(Converter) // or // .doWrite(Map<String, Object>) .doWrite(TemplateModel); public class TemplateModel { @DocProperty(render = TextRenderPolicy.class) private String name; @DocProperty(value = "created_time", converter = LocalDateTimeStringConverter.class) private LocalDateTime dateTime; @DocProperty(render = ItemsRenderPolicy.class) private List<String> items; @DocTable private List<TableModel> table; // Getter & Setter } ``` 2. Builders-style API ```java // for custom writing // global configure builder DocConfigure config = DocConfigure.builder().pageSize(A4).header(...).build(); try (DocWriter writer = FesodDoc.write(pathname).configure(config).build()) { // paragraph builder DocParagraph p1 = FesodDoc.writeParagraph() .text("Title") .style(DocStyles.STYLE_TITLE) .build(); DocItem i1 = FesodDoc.writeItem().text("This is content1.").build(); DocItem i2 = FesodDoc.writeItem().text("This is content2.").break().build(); DocImage image = FesodDoc.writeImage(image_pathname).build(); DocItem i3 = FesodDoc.writeItem().image(image).build(); // rendered // This is content1.This is content2.\n // Image DocParagraph p2 = FesodDoc.writeParagraph(i1, i2, i3) .style(DocStyles.bold().fontSize(16)) .build(); // inline-table builder DocTable t = FesodDoc.writeTable() .head(HeadBuilder.forSimple("ID", "Name") .body(List<?>) .registerWriteHandler(Handler) .build(); // or // writer.add(p1); // writer.add(p2); writer.addAll(p1, p2, t); // auto close && writer.finish() } ``` 3. Mixed API (1 + 2) For simple linear documents, use the fluent API for processing. For highly complex custom layouts, use the builders API to process in chunks. > NOTE: The above methods, functions, and annotation names are only for style > description and design reference, and are not the final API. These are some of my initial thoughts. Looking forward to any thoughts or suggestions. GitHub link: https://github.com/apache/fesod/discussions/946 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
