Component Design for CYOAG

This document describes the ReactJS component hierarchy for CYOAG. This includes a description of the component state, on which the React component structure depends. In other words, depending on the state of the top-most parent component, it will be decided which descendents will be rendered and what their content will be. This can be thought of, in some sense, as a state tree, and that is how this component documentation will be structured. Each node in this tree represents a component, and each branch from that node represents a potential data state.

Using the top-most node as an example, we render the CyoagMain component. If there is a session cookie on the page to begin with, then the CyoagMain component's children will be a story component and its children. Otherwise, the CyoagMain component's children will represent login UI elements so that the user can log in and obtain a session ID, at which point the state will update so that the CyoagMain component will re-render with different children.

Component Hierarchy

A brief overview of components and their relationships

• <CyoagMain> The top-most ReactJS component, and that which manages application state
  • <HeaderBar> header bar of the page, including title
  • <MainColumn> main section of the page, containing story content, navigation, voting, and authoring
    • <Story> includes review snippet, previous path choice snippet, and node snippet, as appropriate
    • <Votification> if user logged in, otherwise <VotificationLogin>
    • <Paths> display paths out from the current node
      • <CollapsedPaths> up to four paths with others link-gated, otherwise <ExpandedPaths>
    • <Authoring> instructions and input fields for users to author new story paths and nodes
      • <CollapsedAuthoring> a link to reveal authoring elements, otherwise <ExpandedAuthoring>
  • <OptionsColumn> smaller side section of page, containing options, login/logout, and miscellany
  • <Login> if no session marked in cookie, otherwise <Logout>
  • <FooterBar> footer bar of the page, including license, links, etc

State and Prop Design

Preliminary design for state and prop management on components

• <CyoagMain>

  The main component maintains the state for the entire application. This is done by defining an admittedly complex state, as well as functions for modifying state, then passing the functions down to child components as props. In many cases, child components will propagate these props down to their children as well.

  Meanwhile, the main component will act not only as a state manager through which children can change state and initiate re-renders; the main component will also be the central point from which AJAJ(X) calls are made to the backend. When a child needs to communicate with the backend, this will be done by proxy through the main component.

  No descendent of CyoagMain is intended to maintain its own state.

  State

  • nodeId - the ID of the current node for positioning

  • reviewSnippet - the trailing end of the previous node, as a reminder

  • lastPathSnippet - path snippet chosen to lead to the current node

  • nodeSnippet - main plot text for the current node

  • loggedIn - simple Boolean to track whether a user is logged in

  • votificationStatus - whether the current user regards the current node with positive, negative, or neutral sentiment

  • pathsCollapsed - whether paths should appear collapsed or expanded

  • pathList - a list of all paths out from the given node, sorted by votification, and displayed collapsed or uncollapsed based on the pathsCollapsed state

  • authoringCollapsed - whether authoring should appear collapsed or expanded

  • options - JSON object listing usage options (feature planning in ideation)

  Props

  No props are used by the CyoagMain component. It only maintains state, and passes properties of its state down to its descendents as props of their own.