docs: expand the write/fill pages and replace their screenshots with grids - #979
docs: expand the write/fill pages and replace their screenshots with grids#979nkuprins wants to merge 25 commits into
Conversation
Replaces the PNG screenshots of template and result spreadsheets with semantic HTML tables styled via a new .xl-sheet ruleset, so the examples are selectable, searchable and theme-aware instead of fixed-size images. Also swaps sample data placeholders to locale-neutral names in the English docs.
|
This is intentionally a draft because I still have to polish and reverify... But the core part is already done. |
bengbengbalabalabeng
added
the
PR: developing
The .xl-sheet rules leave custom.css for src/css/xl-sheet.css, registered as a second customCss entry. Geometry is expressed in Excel's own units and classes are named after the spreadsheet value they render (xl-fill-red, xl-fs-20). Adds styles for pictures, comment and dropdown overlays, and sheet tabs.
Each grid keeps its first and last data rows with an ellipsis row between, and uses the value-named style classes.
Adds a table of the {name}, {.name}, {list.name} and escaped forms with what
fills each, plus notes on mixing placeholders with text and on unfilled
placeholders being cleared. Result grids are shortened.
Drops the trailing empty column and the repeated data rows.
The strategy example now uses a three-level header where names repeat in both directions, with one grid per strategy, and explains why AUTO leaves a vertical merge below the first header row unmerged.
Adds a table mapping each field type to its converter, notes that a picture is stretched to its cell, and documents the multi-image WriteCellData form. The result screenshots become grids drawing a sample SVG.
Documents that includeColumnFieldNames follows the POJO field order unless orderByIncludeColumn is set, and that @ExcelProperty index is an absolute position, so a skipped index leaves an empty column. Also fixes the includeColumnFiledNames typo and the Java 9 Set.of call.
The grids now carry the sheet tabs they produce, so the single-sheet, multi- sheet and table results are told apart, with a line on what each writes.
Shows what the three approaches write. The Chinese page also switches its sample data to 字符串, matching write/merge.
The comment and dropdown results are drawn open in the grid, and the dropdown handler gains the usage snippet that registers it.
The 19 PNGs under static/img/docs/write are no longer referenced by any page.
nkuprins
changed the title
Includes listFill_file.png, which only appears as a path inside a code sample in the contribute-doc guide and is not loaded by any page.
bengbengbalabalabeng
removed
the
PR: developing
|
Hi, @nkuprins Regarding the Chinese documentation, could you please consider me as a collaborator for this PR? I would like to assist in modifying the Chinese documentation and directly submit it to this PR. I have preliminarily reviewed the PR content and I think I might make some changes:
Please let me know if you need any help. |
Sure! You are very welcome to help! |
|
Optimize the CSS of the
This is the local preview result. How about it? 
|
Good! |
Hi, @nkuprins I have completed these modifications. Please preview the website effect locally and review it. BTW, since I was involved in the collaboration of this PR, the code review process will be handled by other community members. |
|
Have u seen the style page? For me, the tables lack colours now except for the header Before:
Now:
|
|
All the css style changes now LGTM! I will verify the text changes later |
Data ListThe examples further down all fill from this helper: private List<FillData> data() {
List<FillData> list = ListUtils.newArrayList();
for (int i = 0; i < 10; i++) {
FillData fillData = new FillData();
fillData.setName("John Doe" + i);
fillData.setNumber(5.2);
fillData.setDate(new Date());
list.add(fillData);
}
return list;
}If we do this, note that at
|
|
I also updated PR description Thank you for the help and collaboration! |
3 participants
Purpose of the pull request
Closed: #978
What's changed?
Screenshots in the
write/andfill/docs become HTML grids styled bywebsite/src/css/xl-sheet.css.In general, some screenshots were not aligned with the code and vice versa. For example, Fill Multiple Lists Together, had
data1horizontal on the image, but the code never usedWriteDirectionEnum.HORIZONTAL. In that case, I updated the code snippet with the horizontal part. Where a page leaned on the screenshot for what the text never said, the explanation is added too.fill/fill.md{name}vs{.name}vs{list.name}, escaping, unsupplied placeholderswrite/image.mdWriteCellData,UrlImageConverterfetch policywrite/head.mdwrite/pojo.mdincludeColumnFieldNamesordering andindexgaps, both grouped under Column Order; fixes a typo and a Java 9Set.ofcallwrite/merge.mdwrite/extra.mdis consolidated herewrite/extra.mdwrite/merge.mdwrite/sheet.mdWriteTablewrites its own headerwrite/simple.mdwrite/style.md,write/format.md.xl-sheetrules moved out ofcustom.cssintosrc/css/xl-sheet.css, with light/dark theming;divandpallowed inMD033; deletes the 31 replaced PNGsCollaboration
@delei joined this PR as a collaborator and contributed the
xl-sheetCSS rework(container element, light/dark theme support, palette and spacing), the Chinese wording pass,
and the documentation restructuring/rewording listed above.
Browsers
Verified in the latest Microsoft Edge, Firefox, Brave, and Chrome
Chinese
The
zh-cnpages mirror the English ones. I don't speak Chinese, so they started out AI-translated. @delei has since reviewed and corrected the wording.Checklist