chore (demo-app) : Demo App Blog Post (#933)

asana: https://app.asana.com/0/1204008699308084/1208082471520105/f
Adding new blog post and contribution guide

---------

Co-authored-by: flochtililoch <[email protected]>
Co-authored-by: Florent Bonomo <[email protected]>
Co-authored-by: Hardin Gray <[email protected]>

docs/guide_demo_app_contribution.md

@@ -0,0 +1,168 @@
+---
+id: guide_demo_app_contribution
+title: Demo App Contributor Guide
+sidebar_label: Demo App Contributor Guide
+---
+
+## Folder Structure
+
+### Index
+
+Every page (or tab) in the app is represented as a folder and will have an associated index file. Any partial/fragment called by an example should reside in the same directory.
+`ui/` , `case-studies/` , `navigation/` , `advanced/` are self-contained folders for each tab on the home screen. We follow the same structure for any pages inside.
+
+### Includes
+
+All included files go under `_includes/` folder to contain reusable files across the app. Eleventy surfaces its contents in the root:
+
+1. `templates/`
+   1. `list.xml.njk`: Renders a list of items, each linking to a different screen.
+   1. `section-list.xml.njk`: Renders a section list of items with subtitles.
+   1. `tab.xml.njk`: Basic tab structure for tabs on home screen.
+   1. `styles.xml.njk`: Contains re-usable styles across the app.
+   1. `base.xml.njk`: Base template for all the screens. Can be extended by providing custom styles and content.
+   1. `scrollview.xml.njk`: Extends `base.xml.njk` to provide a scroll view for any screen that extends it.
+   1. `loading-screen.xml.njk`: Included as a loading screen in other templates.
+   1. `header.xml.njk`: Used to render the header button logic.
+1. `icons/` : All icons used across the app go into this folder.
+1. `macros/` : Folder that includes all reusable macros. Each macro should have a separate folder with `index.xml.njk` containing the definition along with `styles.xml.njk` containing the styles.
+
+### Examples with multiple demonstrations
+
+<img src="/img/options_example.png" width="300" />
+
+For screens with a single demonstration, use `index.xml.njk` to include the logic.
+
+For screens with multiple demonstrations, each demonstration should be added through a separate file. The root `index.xml.njk` of the example styles include styles and an index file inside each demonstration folder. Any style common to multiple demonstrations of an example can be included in the example’s `index.xml.njk`. For example:
+
+```sh
+options/
+  no-options/
+    index.xml.njk
+    styles.xml.njk # any style specific to no-option demonstration.
+  one-option/
+    index.xml.njk
+    styles.xml.njk
+  two-options/
+    index.xml.njk
+    styles.xml.njk
+  index.xml.njk # includes all styles.xml.njk and index.xml.njk files
+```
+
+Order to lookup a style declaration: `style.xml.njk` of the demonstration → `styles` block in example’s `index.xml.njk` → `_includes/styles.xml.njk`
+
+## Eleventy’s Front Matter
+
+Metadata used to define variables or settings that are used by eleventy while processing an .njk file. More details in [11ty's Front Matter data reference](https://www.11ty.dev/docs/data-frontmatter/)
+
+### Built-in Properties
+
+- `permalink`: The URL where the page will be available. In our case, the .xml file output. `/_data/eleventyComputed.js` computes this automatically.
+- `tags`: List of tags associated with the file. These tags can be used to categorize or filter files. For example, you might have a blog post with the tags ["programming", "python", "tutorial"]. These tags could be used to find all blog posts about programming, or all blog posts about Python.
+
+### Custom Properties
+
+- `hv_tab_id`: An identifier for a tab on the home screen. Used inside `tab.xml.njk` for selecting the tab in tab bar
+- `hv_button_behavior`: A variable that controls the behavior of the header button on the page. In this case, can have values `"close"`, `"none"` and (default) `"back"`
+- `hv_list_tags`: Used to specify a list of `tags` that should be displayed on the page. All files specifying a certain `hv_list_tags` as their `tags` are included in the list.
+- `hv_title`: The title of the page. This could be used in a `<title>` tag in the HTML head, or as a heading in the body of the page.
+- `hv_open_modal`: Opens the example in a new modal instead of a screen if set to `true`
+
+## Rendering List Items
+
+<img src="/img/rendering_list_items.png" width="300" />
+
+To render a list view as shown above:
+
+1. In `ui/index.xml.njk`, include `templates/list.xml.njk` and define `hv_list_tag`: "Styling" inside the metadata:
+
+```xml
+---
+permalink: "/ui/styling/index.xml"
+hv_title: "Styling"
+hv_button_behavior: "back"
+---
+{% set hv_list_tag = "styling" %}
+{% include "templates/list.xml.njk" %}
+```
+
+2. In `ui/styling/button/index.xml.njk`, define the tag which this item links to (in our case styling):
+
+```xml
+---
+permalink: "/ui/styling/button/index.xml"
+tags: "styling"
+hv_title: "Button"
+hv_button_behavior: "back"
+---
+{% extends 'templates/scrollview.xml.njk' %}
+{# Custom logic for showing content after clicking UI Elements list item #}
+```
+
+## Rendering Section List of Items
+
+Renders item similar to list but also has sub titles to further group them
+
+Uses `hv_section_list_tag` to group items.
+<img src="/img/rendering_section_list_items.png" width="300" />
+
+## Conventions
+
+### Href
+
+All the href paths should start with `/hyperview/public/` . This ensures that requested resource on both github pages and local setup is consistent.
+
+### Case
+
+1. File names, style ids are to follow kebab case, i.e. custom-select, custom-select-bold
+1. style ids and element ids should not overlap. i.e., `<style id="container" />` and `<view id="container" />`
+
+### Files
+
+1. Every file ends with a line break
+
+### Front matter
+
+1. All custom front matter attributes start with prefix `hv_` . example: `hv_button_behavior`
+1. Built-in Properties come first followed by custom properties
+
+### Styles
+
+1. Include styles re-used across multiple screens inside `_includes/styles.xml.njk`
+
+### XML attributes
+
+We accept two formats to render attributes of an XML element:
+
+1. inline (provided that the total number of characters does not exceed 80)
+1. one attribute per line
+
+When rendering the attributes inline, the element closing delimiter and the element closing tag should be on the same line. If the element is a self closing tag, there should be a single space between the last attribute's value and the self closing tag. If the element is not a self closing tag, there should be no leading space before the element delimiter.
+When rendering one attribute per line, the element delimiter should be rendered on a new line, and the indentation level should match the element opening tag. Use alphabetical order for XML element attributes, exception made for id which should be first attribute of the element.
+
+i.e:
+
+**Do's**
+
+```xml
+  <text id="foo"></text>
+  <behavior href="/" />
+  <behavior
+    href="/"
+    action="new"
+  />
+```
+
+**Dont's**
+
+```xml
+  <text id="foo" ></text>
+  <behavior href="/"/>
+  <behavior
+    href="/"
+    action="new"/>
+```
+
+## Getting Started with Demo App
+
+Refer to [this guide](https://github.com/Instawork/hyperview?tab=readme-ov-file#getting-started) to setup demo app locally.

website/blog/2024-08-20-Introducing-New-Demo-App.md

@@ -0,0 +1,44 @@
+---
+author: Rohan Kumar
+authorURL: https://github.com/rohankumar1999
+title: Introducing the New Demo App
+---
+
+The Hyperview demo app was introduced at the same time as the first public release of Hyperview - its goal has always been to showcase the Hyperview functionality through various examples, but it didn’t receive the same attention as the main Hyperview codebase did, in order to scale properly. In particular, the examples code was made of verbose static XML files, that contained a lot of duplication and style inconsistencies. In order to see the examples in action, developers had to clone the Hyperview repository, install the packages, install the mobile runtime of their choice, and run a local server. All of these issues contributed to a less than ideal user and developer experience.
+
+But thanks to some recent development on this project, we can now overcome all these pain points. It is with great excitement that we announce an overhaul of our Hyperview demo app.
+
+### Reduced Markup, Increased Readability
+Using nunjuck’s template inheritance, we abstracted away common markup and styles to focus on the content of the screen.
+
+| Before | After |
+| -------- | ------- |
+| <img src="/img/markup_before.gif" width="400" /> | <img src="/img/markup_after.png" width="450" /> |
+
+### Introduction of Macros
+We make use of macros, another functionality of nunjuck templates, to abstract common styles and markup under reusable functions. They helped us reduce the footprint of the XML code throughout the examples. See the example below for the button XML code:
+
+| Before | After |
+| -------- | ------- |
+| <img src="/img/macro_before.png" width="400" /> | <img src="/img/macro_after_definition.png" width="700" /> <p style="text-align: center;"> **+** </p>   <img src="/img/macro_after_invocation.png" width="700" /> |
+
+### Flattened Hierarchy to Simplify Navigation
+We flattened the navigation hierarchy to make it easier to find examples. Prior to this, developers had to navigate through multiple screens just to land at an example. This was made possible by implementing a tab bar layout, and a segmented control layout inside each tab.
+
+Now you are just a tap or two away from reaching the example you wish to refer to.
+
+| Before | After |
+| -------- | ------- |
+| <img src="/img/navigation_before.gif" /> | <img src="/img/navigation_after.gif" /> |
+
+### Accessible through your Browser!
+A web version of our demo app is just a link away rather than going through the process of installing an application on your phone.
+
+Now save your time by skipping the whole installation process of a mobile app!
+
+Check it out now: [Live examples](https://hyperview.org/docs/example_live)
+
+<img src="/img/web_version.png" />
+
+### Surfacing community custom Hyperview components
+Hyperview was designed early on to be extensible; although support for custom elements and behaviors was available from early Hyperview versions, it was never clearly surfaced to our users. We now have a dedicated section in the demo app for community-built components, under the “Advanced” tab. We’d love to showcase your custom component in our demo app! Refer to [this guide](https://hyperview.org/docs/guide_demo_app_contribution) for rules and practices on getting started with contributing to the demo app.

website/sidebars.json

@@ -4,7 +4,8 @@
       "guide_introduction",
       "guide_installation",
       "guide_html",
-      "guide_navigation"
+      "guide_navigation",
+      "guide_demo_app_contribution"
     ]
   },