DOCSEARCHbyAlgolia
Submit Docs

Hyperview Documentation

repository·master·Indexed 23 days ago

https://github.com/instawork/hyperview

A hypermedia framework and React Native client for building server-driven mobile applications using Hyperview XML (HXML). Hyperview allows developers to update mobile app UIs and logic instantly via a backend server, bypassing app store review cycles and eliminating API version fragmentation. The framework is backend-agnostic and works with any HTTP server or static XML files.

Tokens
68.6K
Snippets
131
Records
283
Agent score
82%

What's inside Hyperview

  1. What is Hyperview?

    master

    Hyperview is a hypermedia format and React Native client used to develop server-driven mobile applications. Instead of traditional native development where the app logic and UI are bundled in the binary, Hyperview screens are rendered by fetching Hyperview XML (HXML) from a server.

    Key benefits include:

    • Server-driven UI: The backend controls layout, content, and actions via HXML.
    • Instant Updates: Deploy changes to your backend to update the app instantly without waiting for App Store reviews.
    • No API Versioning: Users always run the most recent version of the UI logic, eliminating version fragmentation.
    • Backend Agnostic: Works with any HTTP server (Django, Rails, Node, etc.) or even static XML files.

  2. Common mobile interactions in Hyperview

    master

    Hyperview provides behaviors to implement standard mobile UI patterns using XML. Key interaction patterns include:

    • Navigation: Moving between screens, including custom screen loading states and delayed navigation (moving to a screen after a server response).
    • List Interactions: Implementing Pull to refresh (swipe-down gesture), Infinite scroll (loading more items when reaching the bottom), and Lazy loading (loading parts of a screen when scrolled into view).
    • UI Components: Using Tabs to load different subsections of a screen, and building Basic forms (text inputs with validation and submission indicators) or Advanced forms (radio buttons and tag selectors).
    • Communication: Using Event dispatch to communicate between different screens via Hyperview events.

  3. Real-world Hyperview implementations

    master

    Hyperview can be used to build production-grade applications. Examples of complex implementations include:

    • Instawork for Business: A production app utilizing tabs, pull-to-refresh, infinite scroll, form submissions, navigation, and local interactions.
    • Photo sharing app: An application demonstrating comment loading, liking, navigation, and scroll interactions.

  4. What is Hyperview?

    master

    Hyperview is an open-source project designed to bring the benefits of the thin-client, HATEOAS (Hypermedia as the Engine of Application State) paradigm to native mobile apps. It allows developers to define mobile UIs on the server, enabling instant updates without requiring users to download new app binaries from an app store.

    The project consists of two core components:

    1. Hyperview XML (HXML): An XML-based format used to describe native mobile UIs. It includes support for common UI elements (headers, scroll views, lists, text fields, etc.), styling, and a behavior syntax for user interactions (touches, gestures, input) that does not require client-side scripting.
    2. Hyperview Client: A cross-platform library implemented in React Native that renders HXML. It can be embedded into existing mobile applications or used to build entirely new apps from scratch.

    Comparison Summary:

    Web ParadigmHyperview Paradigm
    HTMLHXML
    Web BrowserHyperview Client

  5. The <doc> element structure and usage

    master

    The <doc> element is the mandatory root element of a Hyperview XML payload. It serves as the container for the application's screens or navigation structure.

    Key Rules:

    • Root Only: A <doc> element can only appear at the root of a Hyperview XML document.
    • Screens: A <doc> can contain multiple <screen> elements. Only the first <screen> in the document is rendered immediately. Subsequent <screen> elements are used for prefetching or as loading states for future transitions.
    • Navigation: A <doc> can contain a single <navigator> element.
    • Exclusivity: You cannot mix <screen> and <navigator> elements within the same <doc>. You must choose one pattern: a document containing screens, or a document containing a navigator.
    • Namespace: It is recommended to define the default XML namespace on the <doc> element so it applies to all children.
    <!-- Example of a <doc> containing multiple screens -->
<doc xmlns="https://hyperview.org/hyperview">
  <screen id="main">
    <styles />
    <body />
  </screen>

  <screen id="preloadScreen">
    <styles />
    <body />
  </screen>
</doc>

<!-- Example of a <doc> containing a <navigator> -->
<doc xmlns="https://hyperview.org/hyperview">
  <navigator id="root" type="stack">
    <nav-route id="home" href="/home.xml" />
  </navigator>
</doc>

  7. Mix <behavior> elements with behavior attributes on parent elements

    master

    You can define behaviors by either nesting <behavior> elements inside a parent or by using behavior attributes directly on the parent element. These two approaches are functionally equivalent. For example, a <view> can have a trigger and href defined as attributes, while still containing additional <behavior> child elements for other triggers.

    <view style="Button" trigger="press" href="/display">
  <behavior trigger="longPress" href="/edit" target="new" />
  <text style="Button__Label">Item</text>
</view>

  8. Define visual styles using the <styles> element

    master

    In Hyperview, the <styles> element is used to define the visual appearance of elements within a screen. It acts as a container for one or more <style> elements. To apply a style to a UI element (like a <view>), you define a <style> with a unique id inside the <styles> block and then reference that id using the style attribute on the target element.

    Rules for <styles>

    • Placement: The <styles> element must be a direct child of a <screen> element.
    • Cardinality: There should be only one <styles> child element per screen.
    • Attributes: The <styles> element itself accepts no attributes; its sole purpose is to group <style> elements.
    <doc xmlns="https://hyperview.org/hyperview">
  <screen id="main">
    <styles>
      <style id="Main" flex="1" backgroundColor="red" />
    </styles>
    <body>
      <view style="Main" />
    </body>
  </screen>
</doc>

  9. Apply Layout rules in Hyperview

    master

    Hyperview supports layout properties from React Native. Most elements support these rules, though some exceptions like <spinner> exist.

    Key constraints for layout properties:

    • Units: For properties like top, left, bottom, right, width, height, margin, and padding, you must use points or percentages. Ems and other CSS units are not supported.
    • Positioning: The default position is relative. Use absolute to position a child relative to its parent using specific logical pixel offsets.
    • Overflow: overflow: visible only works on iOS. On Android, all views will clip their children.

  10. How the <modifier> element works for interactive styles

    master

    The <modifier> element allows you to define temporary style overrides based on the local interactive state of a UI element (such as being focused, pressed, or selected).

    Key Behaviors

    • Merging: When a modifier's condition is met, its <style> attributes are merged with the parent <style>'s default rules.
    • State Propagation: A modifier state applied to a parent element also applies to all its children. If a child element has its own <modifier> matching that same state, the child's modifier will also trigger.
    • Requirement: A <modifier> must be a direct child of a <style> element.
    • Pressable Elements: The pressed modifier only takes effect on elements that have behavior attached (e.g., via an href).
    <style id="Input" borderBottomColor="#E1E1E1" borderBottomWidth="1">
  <modifier focused="true">
    <style borderBottomColor="#4778FF" />
  </modifier>
</style>

  11. Add multiple behaviors to UI elements using the <behavior> element

    master

    The <behavior> element allows you to attach multiple interactive behaviors to a single UI element (such as <view>, <text>, <image>, etc.). This is useful for elements that need to respond to different user interactions, such as a single button that responds to both a short press and a long press.

    Supported parent elements that can contain <behavior> as a direct child include:

    • <view>
    • <text>
    • <image>
    • <list>
    • <section-list>
    • <option>
    <view style="Button">
  <behavior trigger="press" href="/display" />
  <behavior trigger="longPress" href="/edit" target="new" />
  <text style="Button__Label">Item</text>
</view>

  12. Style selected tabs with `<modifier>`

    master

    To visually indicate which tab is active, use the <modifier> element within your <style> definitions. When an <option> is selected, any <modifier selected="true"> block inside its style (or the style of its children) will be applied.

    Note that modifier states apply to the children of an <option> element, allowing you to change the look of tab labels specifically when selected.

    <style id="Tab" backgroundColor="white" flex="1" flexDirection="row" justifyContent="center" alignItems="center">
  <modifier selected="true">
    <style backgroundColor="#ddd" />
  </modifier>
</style>

<style id="Tab__Label" fontSize="18" fontWeight="normal">
  <modifier selected="true">
    <style fontWeight="bold" />
  </modifier>
</style>