<commit_before># A component hierarchy example: the `patrons` module

## Introduction

Building a Stripes application consists of plugging Stripes modules
together. Creating modules is the core development activity in
Stripes: most UI developers will spend most of their time putting
together modules that provide an interface to some functionality
provided on the server-side.

Stripes modules are composed of components. Stripes components are
[React](https://facebook.github.io/react/) components, wrapped in some
additional functionality. Most importantly, a _connected component_ is
one that uses the services of the stripes-connect library to connect
it to data -- most usually, data maintained via an Okapi-mediated
FOLIO module, but potentially also other RESTful web-services or even
purely local (non-persistent) data.

This document illustrates how components can work together as a
module: in particular, it discusses how the components of a
hypothetical `patrons` fullpage module that support search and display
of patron records and associated data such as holds and loans.

Module names are written in all lower-case, with words separated by
hyphens and set in code font `like-this`. Component names are written
in CamelCase and set in bold, **LikeThis**.

<!-- ../../okapi/doc/md2toc -l 2 component-hierarchy.md -->
* [Introduction](#introduction)
* [The module](#the-module)
    * [Metadata describing the module](#metadata-describing-the-module)
    * [State within the module](#state-within-the-module)
* [Components](#components)
    * [Patrons](#patrons)
    * [TopBar](#topbar)
        * [SearchBox](#searchbox)
            * [SearchSettings](#searchsettings)
    * [PatronRouter](#patronrouter)
    * [SearchResults](#searchresults)
        * [SearchResult](#searchresult)
    * [Display](#display)
        * [Holds](#holds)
            * [HoldBrief](#holdbrief)
                * [ItemBrief](#itembrief)
        * [Loans](#loans)
            * [LoanBrief](#loanbrief)
        * [Blocks](#blocks)
* [Appendix: additional issues to be discussed](#appendix-additional-issues-to-be-discussed)




## The module


### Metadata describing the module

Each Stripes module is described by metadata -- some of it affecting
how it functions, some merely descriptive. For a `patrons` module, the
metadata might look like this:

```
{
  'name': 'Patrons',      // Human-readable caption used for menus, etc.
  'type': 'fullpage',     // As opposed to "menubar", “popup”, etc.
  'route': '/patrons',    // The module runs when a URL ending with this path is used
  'component': 'Patrons'  // Name of the top-level component loaded for the specified route
}
```

The metadata of the various modules making up a Stripes application is
aggregated by stripes-loader. (Code-loading is handled asynchronously
so that a module's code is sent to the browser when visiting a
route that uses it.)


### State within the module

Each stripes module maintains all of its state in a single pool. (See
[**How state is stored**](../../stripes-connect/api.md#how-state-is-stored)
for details).
Each piece of state has a name, and may be accessed by multiple
components. Often, only one component will be responsible for making
changes to a given piece of state, while others only inspect it. In
this case, we might say that the first component "owns" that piece of
state. In the descriptions that follow, we will note which pieces of
state the components of a `patrons` module might access, and the mode of access
(**C** = create,
**R** = read,
**U** = update,
**D** = delete).

State may be persisted to a RESTful service (most often, Okapi, the
FOLIO API gateway) or it may be held locally, within the browser
session. Below, we will refer to the former as Okapi data and the
latter as local state.

<commit_msg>Update link to Stripes-Connect "api.md" document.<commit_after># A component hierarchy example: the `patrons` module

## Introduction

Building a Stripes application consists of plugging Stripes modules
together. Creating modules is the core development activity in
Stripes: most UI developers will spend most of their time putting
together modules that provide an interface to some functionality
provided on the server-side.

Stripes modules are composed of components. Stripes components are
[React](https://facebook.github.io/react/) components, wrapped in some
additional functionality. Most importantly, a _connected component_ is
one that uses the services of the stripes-connect library to connect
it to data -- most usually, data maintained via an Okapi-mediated
FOLIO module, but potentially also other RESTful web-services or even
purely local (non-persistent) data.

This document illustrates how components can work together as a
module: in particular, it discusses how the components of a
hypothetical `patrons` fullpage module that support search and display
of patron records and associated data such as holds and loans.

Module names are written in all lower-case, with words separated by
hyphens and set in code font `like-this`. Component names are written
in CamelCase and set in bold, **LikeThis**.

<!-- ../../okapi/doc/md2toc -l 2 component-hierarchy.md -->
* [Introduction](#introduction)
* [The module](#the-module)
    * [Metadata describing the module](#metadata-describing-the-module)
    * [State within the module](#state-within-the-module)
* [Components](#components)
    * [Patrons](#patrons)
    * [TopBar](#topbar)
        * [SearchBox](#searchbox)
            * [SearchSettings](#searchsettings)
    * [PatronRouter](#patronrouter)
    * [SearchResults](#searchresults)
        * [SearchResult](#searchresult)
    * [Display](#display)
        * [Holds](#holds)
            * [HoldBrief](#holdbrief)
                * [ItemBrief](#itembrief)
        * [Loans](#loans)
            * [LoanBrief](#loanbrief)
        * [Blocks](#blocks)
* [Appendix: additional issues to be discussed](#appendix-additional-issues-to-be-discussed)




## The module


### Metadata describing the module

Each Stripes module is described by metadata -- some of it affecting
how it functions, some merely descriptive. For a `patrons` module, the
metadata might look like this:

```
{
  'name': 'Patrons',      // Human-readable caption used for menus, etc.
  'type': 'fullpage',     // As opposed to "menubar", “popup”, etc.
  'route': '/patrons',    // The module runs when a URL ending with this path is used
  'component': 'Patrons'  // Name of the top-level component loaded for the specified route
}
```

The metadata of the various modules making up a Stripes application is
aggregated by stripes-loader. (Code-loading is handled asynchronously
so that a module's code is sent to the browser when visiting a
route that uses it.)


### State within the module

Each stripes module maintains all of its state in a single pool. (See
[**How state is stored**](../../stripes-connect/doc/api.md#how-state-is-stored)
for details).
Each piece of state has a name, and may be accessed by multiple
components. Often, only one component will be responsible for making
changes to a given piece of state, while others only inspect it. In
this case, we might say that the first component "owns" that piece of
state. In the descriptions that follow, we will note which pieces of
state the components of a `patrons` module might access, and the mode of access
(**C** = create,
**R** = read,
**U** = update,
**D** = delete).

State may be persisted to a RESTful service (most often, Okapi, the
FOLIO API gateway) or it may be held locally, within the browser
session. Below, we will refer to the former as Okapi data and the
latter as local state.


{'fraction_non_alphanumeric': 0.0929746670148864, 'fraction_numerical': 0.0005223295899712719, 'mean_word_length': 3.9928292046936114, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1848656', 'n_tokens_mistral': 2132, 'n_tokens_neox': 1979, 'n_words': 947}