Reorganize docs: move deprecated features to Obsolete section

[oblomov-dev]

Summary

Reorganized the documentation structure to clearly separate deprecated and obsolete features from active guidance. Moved custom JavaScript, custom controls, and follow_up_action documentation to a new "Obsolete" section, added comprehensive new snippets and guidance pages, and enhanced existing documentation with failure handling and limitations.

Key Changes

Documentation Reorganization

• Created new "Obsolete" section in the cookbook sidebar for deprecated patterns:

  • Moved custom_js.md from advanced/extensibility/ to cookbook/expert_more/
  • Added new custom_controls.md documenting obsolete custom control patterns
  • Added new follow_up_action.md explaining the deprecation and migration path

• Renamed and reorganized sidebar sections:

  • "Utilities" → "Patterns, Helpers" with new Snippets page at the top
  • Moved "Experimental" section from Advanced to Cookbook level
  • Removed Custom JavaScript from Advanced/Extensibility (now in Obsolete)

New Content

• snippets.md — Copy-paste starting points for common app patterns:

  • Basic App Structure (skeleton with lifecycle dispatch)
  • Selection Screen (input form with binding)
  • Write Output (using cl_demo_output)
  • Basic Table (read-only with columns)
  • Table with Filtering & Sorting (with p13n features)

• custom_js.md (rewritten) — Comprehensive security warning:

  • Explains XSS risks, CSP breakage, and audit problems
  • Lists safer alternatives (standard UI5, custom controls, built-in actions)
  • Shows how it works if absolutely necessary
  • Emphasizes never injecting untrusted input

• custom_controls.md (new) — Deprecation guide:

  • Table mapping old custom controls to new built-in client->action() calls
  • Explains why built-in actions are preferred
  • Links to replacement documentation for each action

• follow_up_action.md (new) — Migration guide:

  • Explains the shift from free-text JavaScript to typed client->action() calls
  • Shows before/after code examples
  • References the security rationale on Custom JS page

Enhanced Existing Documentation

• eml.md — Added "Failure Handling" section:

  • Explains FAILED and REPORTED structures (not exceptions)
  • Lists infrastructure exceptions to catch
  • Provides defensive pattern with TRY/CATCH example

• binding.md — Added "Known Limitations" subsection:

  • Documents lack of formal ABAP-to-JSON type mapping
  • Notes issues with p, d, i, n field types
  • Explains need for formatters with date fields

• definition.md — Added "Respect UI5 Control Aggregation Rules" warning:

  • Explains that Z2UI5_CL_XML_VIEW is permissive but UI5 is not
  • Warns about broken rendering from invalid nesting
  • Directs users to check UI5 SDK for aggregation rules

• exception.md — Added "Common Failure Modes" section:

  • Binding-path mismatch (silent failures, browser console clues)
  • Malformed XML (parse errors, unknown controls, wrong aggregations)
  • Where errors surface and how to debug

• websocket.md — Updated link reference from old Custom JS location

Implementation Details

• All new pages follow the existing documentation style with outline frontmatter and warning/tip callouts
• Sidebar configuration updated to use collapsed: true for better organization
• Cross-references between pages (e.g., Custom JS → Custom Controls → built-in actions) guide users to modern patterns
• Deprecated content preserved for users still maintaining legacy code, but clearly marked as obsolete

https://claude.ai/code/session_01NazSkKkjTMYvvV1mGfD33E