bench get-app https://github.com/xlurself/xl_html_reviewer

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=xlurself%2Fxl_html_reviewer)](https://frappegems.com/gems/apps/xlurself/xl_html_reviewer)

XL HTML Reviewer

A Frappe v16 app for publishing HTML documents (such as Business Requirements Documents) for read-only review, and collecting inline, anchored comments on the rendered document without allowing edits.

---

Overview

XL HTML Reviewer lets teams:

• Upload documents as raw HTML (tables, headings, formatting preserved).
• Publish documents to a read-only website view with a stable URL.
• Comment on any selected text: add comments, reply in threads, and resolve discussions.
• Collaborate with multiple users; comments are anchored to the exact text range.

The document itself is never editable on the website—only commenting is allowed, so the published content stays intact while feedback is collected in a sidebar.

---

Features

Document management

• BRD Document doctype: Title, HTML Content (raw HTML), Status (Draft / Review / Approved / Retired), Published flag.
• Draft vs Published: Edit freely in Draft; on Publish, the document becomes read-only and a website URL is generated.
• View on Website: One-click open of the published document at /brd/.

Website view

• Renders HTML exactly as-is (CSS and formatting preserved).
• Clean, document-style layout: wide margins, centered content area, non-editable.
• Read-Only Review Mode indicator.
• Custom navbar/footer aligned with content width.

Commenting (inline)

• Select text in the rendered HTML → floating Add Comment button appears.
• Add Comment opens the comment input in the right sidebar (no modal).
• Comment is anchored to the selected text via stored range data (DOM path + offsets).
• Highlighting: Commented text is highlighted (yellow/orange); active comment highlights in orange.
• Sidebar: Comments listed in a sticky right sidebar; filters: Open / Resolved / All / Mentions.

Collaboration

• Threaded replies: Reply to any comment; replies shown under the comment.
• Resolve: Mark comments as Resolved; resolved comments are visually distinct (greyed/collapsed).
• Multi-user: All logged-in users with access can add comments and replies.
• @mentions: Type @ in comment/reply to mention users (with user search).

Extras

• Comment activity: “Added today” / “Resolved today” summary in the sidebar.
• New Version: Create a new document version and carry over unresolved comments.
• Download PDF: Export the document (with content) as PDF.

Security & UX

• Only logged-in users can view the document page and comment (permission via BRD Document read access).
• Role-based permissions on BRD Document, BRD Comment, BRD Comment Reply.
• Responsive layout; sidebar scrolls independently when there are many comments.

---

User flow

1. Create and publish a document

1. In the Frappe desk, go to BRD Document and create a new document.
2. Enter Title and paste or write HTML Content (raw HTML).
3. Save. Optionally set Status (Draft / Review / Approved / Retired).
4. Click Publish. The document becomes read-only; Published On / Published By are set and a View on Website button appears.
5. Click View on Website (or open /brd/) to open the published view.

2. Review and comment

1. On the document page, read the content (read-only).
2. Select any text in the document.
3. The Add Comment button appears near the selection; click it.
4. The comment input opens in the right sidebar. Type your comment (and optionally use @ to mention users).
5. Click Save Comment. The comment is stored and linked to the selected text; that text is highlighted.
6. Other users can Reply to the comment (threaded) or add new comments on other selections.

3. Resolve and manage comments

1. In the sidebar, use filters: Open / Resolved / All / Mentions.
2. Click a comment (in the list or on highlighted text) to focus it and scroll to the related text.
3. Click Resolve on a comment to mark it resolved; it appears greyed/collapsed under Resolved filter.
4. Use New Version to create a new document and carry over unresolved comments, or Download PDF to export.

---

Technical overview

Stack

• Backend: Frappe v16 (Python).
• Frontend: Vanilla JS (no framework), Jinja2 templates, CSS.
• Data: Frappe DocTypes; no Frappe core modifications.

App structure

om_brd_management/
├── om_brd_management/
│   ├── doctype/
│   │   ├── brd_document/       # BRD Document doctype
│   │   ├── brd_comment/        # BRD Comment doctype
│   │   └── brd_comment_reply/  # BRD Comment Reply doctype
│   ├── www/
│   │   ├── brd.py              # Route handler for /brd/
│   │   └── brd.html            # Document page template (content + sidebar)
│   ├── templates/
│   │   ├── brd_base.html       # Custom base (navbar/footer) for document pages
│   │   └── generators/
│   │       └── brd_document.html
│   └── public/
│       └── js/
│           └── brd_collaboration.js   # Selection, comments UI, API calls
├── hooks.py                    # website_route_rules, base_template_map, website_generators
├── pyproject.toml
└── README.md

Data model

DocType	Purpose
BRD Document	Title, HTML Content, Status, Is Published, Route. Source of truth for the published HTML.
BRD Comment	Parent Document (Link to BRD Document), User, Comment Text, Selected Text Snippet, Range Data (JSON: DOM path + start/end offsets), Is Resolved, Timestamp. Child table: Replies.
BRD Comment Reply	Parent (BRD Comment), User, Reply Text, Timestamp.

Comment range_data stores a serialized DOM range (e.g. startPath, endPath, startOffset, endOffset) so the same text can be highlighted again after reload.

Routes and hooks

• URL: /brd/ where name is the BRD Document name.
• Hooks: website_route_rules maps /brd/ → brd page; base_template_map uses brd_base.html for /brd so navbar/footer match the document layout.

---

Versioning

• Current release version is in VERSION (e.g. 1.0.0).
• Releases are tagged in Git as v1.0.0, v1.1.0, etc. (semantic versioning).

---

Installation

From Git (bench)

cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch main
bench install-app om_brd_management

Replace main with your branch (e.g. version-16 if you use versioned branches).

After install

1. In Role Permission Manager, grant the right roles Read (and optionally Create/Write) on BRD Document, BRD Comment, and BRD Comment Reply so users can open document pages and comment.
2. Create a BRD Document, add HTML content, and Publish; then open View on Website to test commenting.

---

Deploying to Frappe Cloud

1. Push this app to a Git repository (e.g. GitHub).
2. In Frappe Cloud, use a private bench group (custom apps are only supported there).
3. Apps → Add App → Add from GitHub → select repo and branch (e.g. main or version-16).
4. Click Validate App, then Add app, then Deploy the bench group.
5. On your site: Install App → XL HTML Reviewer.
6. In Role Permission Manager, assign permissions for BRD Document (and related doctypes) to the roles that should create/view documents and comment.

No code changes are required for Frappe Cloud; ensure the branch matches your Frappe version (e.g. v16).

---

Contributing

This project uses pre-commit for formatting and linting:

cd apps/om_brd_management
pre-commit install

Tools: ruff, eslint, prettier, pyupgrade.

---

Author

Vinay Saraf
Founder – XLURSELF India Private Limited

---

License

MIT