Skip to content
Snippets Groups Projects
Commit c4434882 authored by Andrey Azov's avatar Andrey Azov
Browse files

Add index page

parent 04f74ee6
No related branches found
No related tags found
No related merge requests found
Pipeline #71747 passed with stages
Stage:
    Stage:
      in 1 minute and 45 seconds
      Hide whitespace changes
      Inline Side-by-side
      Showing
      with 40 additions and 836 deletions
      docs/article/ensembl-select.md
      + 4
      − 76
      View file @ c4434882
      ......@@ -19,87 +19,15 @@ status: published
      >Caution:
      >
      >This page describes **experimental features that are [not yet available](/docs/concurrent-mode-adoption.html) in a stable release**. Don't rely on experimental builds of React in production apps. These features may change significantly and without a warning before they become a part of React.
      >This page describes **experimental features that are not yet available in a stable release**. Don't rely on experimental builds of React in production apps. These features may change significantly and without a warning before they become a part of React.
      >
      >This documentation is aimed at early adopters and people who are curious. **If you're new to React, don't worry about these features** -- you don't need to learn them right now.
      </div>
      <iframe width="560" height="315" src="https://www.youtube.com/embed/C2g37X_uMok" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
      <iframe width="560" height="315" src="https://www.youtube.com/embed/C2g37X_uMok" frameborder="0" allowfullscreen></iframe>
      This page provides a theoretical overview of Concurrent Mode. **For a more practical introduction, you might want to check out the next sections:**
      * [Suspense for Data Fetching](/docs/concurrent-mode-suspense.html) describes a new mechanism for fetching data in React components.
      * [Concurrent UI Patterns](/docs/concurrent-mode-patterns.html) shows some UI patterns made possible by Concurrent Mode and Suspense.
      * [Adopting Concurrent Mode](/docs/concurrent-mode-adoption.html) explains how you can try Concurrent Mode in your project.
      * [Concurrent Mode API Reference](/docs/concurrent-mode-reference.html) documents the new APIs available in experimental builds.
      ## What Is Concurrent Mode? {#what-is-concurrent-mode}
      Concurrent Mode is a set of new features that help React apps stay responsive and gracefully adjust to the user's device capabilities and network speed.
      These features are still experimental and are subject to change. They are not yet a part of a stable React release, but you can try them in an experimental build.
      ## Blocking vs Interruptible Rendering {#blocking-vs-interruptible-rendering}
      **To explain Concurrent Mode, we'll use version control as a metaphor.** If you work on a team, you probably use a version control system like Git and work on branches. When a branch is ready, you can merge your work into master so that other people can pull it.
      Before version control existed, the development workflow was very different. There was no concept of branches. If you wanted to edit some files, you had to tell everyone not to touch those files until you've finished your work. You couldn't even start working on them concurrently with that person — you were literally *blocked* by them.
      This illustrates how UI libraries, including React, typically work today. Once they start rendering an update, including creating new DOM nodes and running the code inside components, they can't interrupt this work. We'll call this approach "blocking rendering".
      In Concurrent Mode, rendering is not blocking. It is interruptible. This improves the user experience. It also unlocks new features that weren't possible before. Before we look at concrete examples in the [next](/docs/concurrent-mode-suspense.html) [chapters](/docs/concurrent-mode-patterns.html), we'll do a high-level overview of new features.
      ### Interruptible Rendering {#interruptible-rendering}
      Consider a filterable product list. Have you ever typed into a list filter and felt that it stutters on every key press? Some of the work to update the product list might be unavoidable, such as creating new DOM nodes or the browser performing layout. However, *when* and *how* we perform that work plays a big role.
      A common way to work around the stutter is to "debounce" the input. When debouncing, we only update the list *after* the user stops typing. However, it can be frustrating that the UI doesn't update while we're typing. As an alternative, we could "throttle" the input, and update the list with a certain maximum frequency. But then on lower-powered devices we'd still end up with stutter. Both debouncing and throttling create a suboptimal user experience.
      The reason for the stutter is simple: once rendering begins, it can't be interrupted. So the browser can't update the text input right after the key press. No matter how good a UI library (such as React) might look on a benchmark, if it uses blocking rendering, a certain amount of work in your components will always cause stutter. And, often, there is no easy fix.
      **Concurrent Mode fixes this fundamental limitation by making rendering interruptible.** This means when the user presses another key, React doesn't need to block the browser from updating the text input. Instead, it can let the browser paint an update to the input, and then continue rendering the updated list *in memory*. When the rendering is finished, React updates the DOM, and changes are reflected on the screen.
      Conceptually, you can think of this as React preparing every update "on a branch". Just like you can abandon work in branches or switch between them, React in Concurrent Mode can interrupt an ongoing update to do something more important, and then come back to what it was doing earlier. This technique might also remind you of [double buffering](https://wiki.osdev.org/Double_Buffering) in video games.
      Concurrent Mode techniques reduce the need for debouncing and throttling in UI. Because rendering is interruptible, React doesn't need to artificially *delay* work to avoid stutter. It can start rendering right away, but interrupt this work when needed to keep the app responsive.
      ### Intentional Loading Sequences {#intentional-loading-sequences}
      We've said before that Concurrent Mode is like React working "on a branch". Branches are useful not only for short-term fixes, but also for long-running features. Sometimes you might work on a feature, but it could take weeks before it's in a "good enough state" to merge into master. This side of our version control metaphor applies to rendering too.
      Imagine we're navigating between two screens in an app. Sometimes, we might not have enough code and data loaded to show a "good enough" loading state to the user on the new screen. Transitioning to an empty screen or a large spinner can be a jarring experience. However, it's also common that the necessary code and data doesn't take too long to fetch. **Wouldn't it be nicer if React could stay on the old screen for a little longer, and "skip" the "bad loading state" before showing the new screen?**
      While this is possible today, it can be difficult to orchestrate. In Concurrent Mode, this feature is built-in. React starts preparing the new screen in memory first — or, as our metaphor goes, "on a different branch". So React can wait before updating the DOM so that more content can load. In Concurrent Mode, we can tell React to keep showing the old screen, fully interactive, with an inline loading indicator. And when the new screen is ready, React can take us to it.
      ### Concurrency {#concurrency}
      Let's recap the two examples above and see how Concurrent Mode unifies them. **In Concurrent Mode, React can work on several state updates *concurrently*** — just like branches let different team members work independently:
      * For CPU-bound updates (such as creating DOM nodes and running component code), concurrency means that a more urgent update can "interrupt" rendering that has already started.
      * For IO-bound updates (such as fetching code or data from the network), concurrency means that React can start rendering in memory even before all the data arrives, and skip showing jarring empty loading states.
      Importantly, the way you *use* React is the same. Concepts like components, props, and state fundamentally work the same way. When you want to update the screen, you set the state.
      React uses a heuristic to decide how "urgent" an update is, and lets you adjust it with a few lines of code so that you can achieve the desired user experience for every interaction.
      ## Putting Research into Production {#putting-research-into-production}
      There is a common theme around Concurrent Mode features. **Its mission is to help integrate the findings from the Human-Computer Interaction research into real UIs.**
      For example, research shows that displaying too many intermediate loading states when transitioning between screens makes a transition feel *slower*. This is why Concurrent Mode shows new loading states on a fixed "schedule" to avoid jarring and too frequent updates.
      Similarly, we know from research that interactions like hover and text input need to be handled within a very short period of time, while clicks and page transitions can wait a little longer without feeling laggy. The different "priorities" that Concurrent Mode uses internally roughly correspond to the interaction categories in the human perception research.
      Teams with a strong focus on user experience sometimes solve similar problems with one-off solutions. However, those solutions rarely survive for a long time, as they're hard to maintain. With Concurrent Mode, our goal is to bake the UI research findings into the abstraction itself, and provide idiomatic ways to use them. As a UI library, React is well-positioned to do that.
      ## Next Steps {#next-steps}
      Now you know what Concurrent Mode is all about!
      On the next pages, you'll learn more details about specific topics:
      # What is Ensembl Select?
      * [Suspense for Data Fetching](/docs/concurrent-mode-suspense.html) describes a new mechanism for fetching data in React components.
      * [Concurrent UI Patterns](/docs/concurrent-mode-patterns.html) shows some UI patterns made possible by Concurrent Mode and Suspense.
      * [Adopting Concurrent Mode](/docs/concurrent-mode-adoption.html) explains how you can try Concurrent Mode in your project.
      * [Concurrent Mode API Reference](/docs/concurrent-mode-reference.html) documents the new APIs available in experimental builds.
      Cras id arcu porttitor, luctus turpis eu, venenatis risus. Curabitur iaculis mauris vitae ipsum euismod, in mattis nisi suscipit. Vestibulum tincidunt suscipit eros. Integer gravida dolor in mi tincidunt, ut luctus lectus consectetur. In vestibulum blandit ipsum, sed pulvinar ipsum posuere eget.
      docs/article/getting-started.md
      + 1
      − 259
      View file @ c4434882
      ......@@ -4,262 +4,4 @@ status: published
      # Getting Started
      Context provides a way to pass data through the component tree without having to pass props down manually at every level.
      In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like these between components without having to explicitly pass a prop through every level of the tree.
      - [When to Use Context](#when-to-use-context)
      - [Before You Use Context](#before-you-use-context)
      - [API](#api)
      - [React.createContext](#reactcreatecontext)
      - [Context.Provider](#contextprovider)
      - [Class.contextType](#classcontexttype)
      - [Context.Consumer](#contextconsumer)
      - [Context.displayName](#contextdisplayname)
      - [Examples](#examples)
      - [Dynamic Context](#dynamic-context)
      - [Updating Context from a Nested Component](#updating-context-from-a-nested-component)
      - [Consuming Multiple Contexts](#consuming-multiple-contexts)
      - [Caveats](#caveats)
      - [Legacy API](#legacy-api)
      ## When to Use Context {#when-to-use-context}
      Context is designed to share data that can be considered "global" for a tree of React components, such as the current authenticated user, theme, or preferred language. For example, in the code below we manually thread through a "theme" prop in order to style the Button component:
      `embed:context/motivation-problem.js`
      Using context, we can avoid passing props through intermediate elements:
      `embed:context/motivation-solution.js`
      ## Before You Use Context {#before-you-use-context}
      Context is primarily used when some data needs to be accessible by *many* components at different nesting levels. Apply it sparingly because it makes component reuse more difficult.
      **If you only want to avoid passing some props through many levels, [component composition](/docs/composition-vs-inheritance.html) is often a simpler solution than context.**
      For example, consider a `Page` component that passes a `user` and `avatarSize` prop several levels down so that deeply nested `Link` and `Avatar` components can read it:
      ```js
      <Page user={user} avatarSize={avatarSize} />
      // ... which renders ...
      <PageLayout user={user} avatarSize={avatarSize} />
      // ... which renders ...
      <NavigationBar user={user} avatarSize={avatarSize} />
      // ... which renders ...
      <Link href={user.permalink}>
      <Avatar user={user} size={avatarSize} />
      </Link>
      ```
      It might feel redundant to pass down the `user` and `avatarSize` props through many levels if in the end only the `Avatar` component really needs it. It's also annoying that whenever the `Avatar` component needs more props from the top, you have to add them at all the intermediate levels too.
      One way to solve this issue **without context** is to [pass down the `Avatar` component itself](/docs/composition-vs-inheritance.html#containment) so that the intermediate components don't need to know about the `user` or `avatarSize` props:
      ```js
      function Page(props) {
      const user = props.user;
      const userLink = (
      <Link href={user.permalink}>
      <Avatar user={user} size={props.avatarSize} />
      </Link>
      );
      return <PageLayout userLink={userLink} />;
      }
      // Now, we have:
      <Page user={user} avatarSize={avatarSize} />
      // ... which renders ...
      <PageLayout userLink={...} />
      // ... which renders ...
      <NavigationBar userLink={...} />
      // ... which renders ...
      {props.userLink}
      ```
      With this change, only the top-most Page component needs to know about the `Link` and `Avatar` components' use of `user` and `avatarSize`.
      This *inversion of control* can make your code cleaner in many cases by reducing the amount of props you need to pass through your application and giving more control to the root components. However, this isn't the right choice in every case: moving more complexity higher in the tree makes those higher-level components more complicated and forces the lower-level components to be more flexible than you may want.
      You're not limited to a single child for a component. You may pass multiple children, or even have multiple separate "slots" for children, [as documented here](/docs/composition-vs-inheritance.html#containment):
      ```js
      function Page(props) {
      const user = props.user;
      const content = <Feed user={user} />;
      const topBar = (
      <NavigationBar>
      <Link href={user.permalink}>
      <Avatar user={user} size={props.avatarSize} />
      </Link>
      </NavigationBar>
      );
      return (
      <PageLayout
      topBar={topBar}
      content={content}
      />
      );
      }
      ```
      This pattern is sufficient for many cases when you need to decouple a child from its immediate parents. You can take it even further with [render props](/docs/render-props.html) if the child needs to communicate with the parent before rendering.
      However, sometimes the same data needs to be accessible by many components in the tree, and at different nesting levels. Context lets you "broadcast" such data, and changes to it, to all components below. Common examples where using context might be simpler than the alternatives include managing the current locale, theme, or a data cache.
      ## API {#api}
      ### `React.createContext` {#reactcreatecontext}
      ```js
      const MyContext = React.createContext(defaultValue);
      ```
      Creates a Context object. When React renders a component that subscribes to this Context object it will read the current context value from the closest matching `Provider` above it in the tree.
      The `defaultValue` argument is **only** used when a component does not have a matching Provider above it in the tree. This can be helpful for testing components in isolation without wrapping them. Note: passing `undefined` as a Provider value does not cause consuming components to use `defaultValue`.
      ### `Context.Provider` {#contextprovider}
      ```js
      <MyContext.Provider value={/* some value */}>
      ```
      Every Context object comes with a Provider React component that allows consuming components to subscribe to context changes.
      Accepts a `value` prop to be passed to consuming components that are descendants of this Provider. One Provider can be connected to many consumers. Providers can be nested to override values deeper within the tree.
      All consumers that are descendants of a Provider will re-render whenever the Provider's `value` prop changes. The propagation from Provider to its descendant consumers (including [`.contextType`](#classcontexttype) and [`useContext`](/docs/hooks-reference.html#usecontext)) is not subject to the `shouldComponentUpdate` method, so the consumer is updated even when an ancestor component skips an update.
      Changes are determined by comparing the new and old values using the same algorithm as [`Object.is`](//developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).
      > Note
      >
      > The way changes are determined can cause some issues when passing objects as `value`: see [Caveats](#caveats).
      ### `Class.contextType` {#classcontexttype}
      ```js
      class MyClass extends React.Component {
      componentDidMount() {
      let value = this.context;
      /* perform a side-effect at mount using the value of MyContext */
      }
      componentDidUpdate() {
      let value = this.context;
      /* ... */
      }
      componentWillUnmount() {
      let value = this.context;
      /* ... */
      }
      render() {
      let value = this.context;
      /* render something based on the value of MyContext */
      }
      }
      MyClass.contextType = MyContext;
      ```
      The `contextType` property on a class can be assigned a Context object created by [`React.createContext()`](#reactcreatecontext). This lets you consume the nearest current value of that Context type using `this.context`. You can reference this in any of the lifecycle methods including the render function.
      > Note:
      >
      > You can only subscribe to a single context using this API. If you need to read more than one see [Consuming Multiple Contexts](#consuming-multiple-contexts).
      >
      > If you are using the experimental [public class fields syntax](https://babeljs.io/docs/plugins/transform-class-properties/), you can use a **static** class field to initialize your `contextType`.
      ```js
      class MyClass extends React.Component {
      static contextType = MyContext;
      render() {
      let value = this.context;
      /* render something based on the value */
      }
      }
      ```
      ### `Context.Consumer` {#contextconsumer}
      ```js
      <MyContext.Consumer>
      {value => /* render something based on the context value */}
      </MyContext.Consumer>
      ```
      A React component that subscribes to context changes. This lets you subscribe to a context within a [function component](/docs/components-and-props.html#function-and-class-components).
      Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). The function receives the current context value and returns a React node. The `value` argument passed to the function will be equal to the `value` prop of the closest Provider for this context above in the tree. If there is no Provider for this context above, the `value` argument will be equal to the `defaultValue` that was passed to `createContext()`.
      > Note
      >
      > For more information about the 'function as a child' pattern, see [render props](/docs/render-props.html).
      ### `Context.displayName` {#contextdisplayname}
      Context object accepts a `displayName` string property. React DevTools uses this string to determine what to display for the context.
      For example, the following component will appear as MyDisplayName in the DevTools:
      ```js{2}
      const MyContext = React.createContext(/* some value */);
      MyContext.displayName = 'MyDisplayName';
      <MyContext.Provider> // "MyDisplayName.Provider" in DevTools
      <MyContext.Consumer> // "MyDisplayName.Consumer" in DevTools
      ```
      ## Examples {#examples}
      ### Dynamic Context {#dynamic-context}
      A more complex example with dynamic values for the theme:
      **theme-context.js**
      `embed:context/theme-detailed-theme-context.js`
      **themed-button.js**
      `embed:context/theme-detailed-themed-button.js`
      **app.js**
      `embed:context/theme-detailed-app.js`
      ### Updating Context from a Nested Component {#updating-context-from-a-nested-component}
      It is often necessary to update the context from a component that is nested somewhere deeply in the component tree. In this case you can pass a function down through the context to allow consumers to update the context:
      **theme-context.js**
      `embed:context/updating-nested-context-context.js`
      **theme-toggler-button.js**
      `embed:context/updating-nested-context-theme-toggler-button.js`
      **app.js**
      `embed:context/updating-nested-context-app.js`
      ### Consuming Multiple Contexts {#consuming-multiple-contexts}
      To keep context re-rendering fast, React needs to make each context consumer a separate node in the tree.
      `embed:context/multiple-contexts.js`
      If two or more context values are often used together, you might want to consider creating your own render prop component that provides both.
      ## Caveats {#caveats}
      Because context uses reference identity to determine when to re-render, there are some gotchas that could trigger unintentional renders in consumers when a provider's parent re-renders. For example, the code below will re-render all consumers every time the Provider re-renders because a new object is always created for `value`:
      `embed:context/reference-caveats-problem.js`
      To get around this, lift the value into the parent's state:
      `embed:context/reference-caveats-solution.js`
      ## Legacy API {#legacy-api}
      > Note
      >
      > React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. The legacy API will be removed in a future major React version. Read the [legacy context docs here](/docs/legacy-context.html).
      Nullam dapibus ligula id dolor molestie, vel lacinia ante consequat. Vestibulum eu magna neque. Integer fermentum ante sit amet ante sagittis, ut mollis lacus maximus. Maecenas cursus magna molestie volutpat lacinia. Fusce vestibulum, elit sit amet semper mattis, quam lectus accumsan felis, eget luctus massa tortor et mauris. Maecenas faucibus dui ex.
      docs/article/using-ensembl.md
      + 1
      − 176
      View file @ c4434882
      ......@@ -4,179 +4,4 @@ status: published
      # Using Ensembl
      Consider this variable declaration:
      ```js
      const element = <h1>Hello, world!</h1>;
      ```
      This funny tag syntax is neither a string nor HTML.
      It is called JSX, and it is a syntax extension to JavaScript. We recommend using it with React to describe what the UI should look like. JSX may remind you of a template language, but it comes with the full power of JavaScript.
      JSX produces React "elements". We will explore rendering them to the DOM in the [next section](/docs/rendering-elements.html). Below, you can find the basics of JSX necessary to get you started.
      ### Why JSX? {#why-jsx}
      React embraces the fact that rendering logic is inherently coupled with other UI logic: how events are handled, how the state changes over time, and how the data is prepared for display.
      Instead of artificially separating *technologies* by putting markup and logic in separate files, React [separates *concerns*](https://en.wikipedia.org/wiki/Separation_of_concerns) with loosely coupled units called "components" that contain both. We will come back to components in a [further section](/docs/components-and-props.html), but if you're not yet comfortable putting markup in JS, [this talk](https://www.youtube.com/watch?v=x7cQ3mrcKaY) might convince you otherwise.
      React [doesn't require](/docs/react-without-jsx.html) using JSX, but most people find it helpful as a visual aid when working with UI inside the JavaScript code. It also allows React to show more useful error and warning messages.
      With that out of the way, let's get started!
      ### Embedding Expressions in JSX {#embedding-expressions-in-jsx}
      In the example below, we declare a variable called `name` and then use it inside JSX by wrapping it in curly braces:
      ```js{1,2}
      const name = 'Josh Perez';
      const element = <h1>Hello, {name}</h1>;
      ReactDOM.render(
      element,
      document.getElementById('root')
      );
      ```
      You can put any valid [JavaScript expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Expressions) inside the curly braces in JSX. For example, `2 + 2`, `user.firstName`, or `formatName(user)` are all valid JavaScript expressions.
      In the example below, we embed the result of calling a JavaScript function, `formatName(user)`, into an `<h1>` element.
      ```js{12}
      function formatName(user) {
      return user.firstName + ' ' + user.lastName;
      }
      const user = {
      firstName: 'Harper',
      lastName: 'Perez'
      };
      const element = (
      <h1>
      Hello, {formatName(user)}!
      </h1>
      );
      ReactDOM.render(
      element,
      document.getElementById('root')
      );
      ```
      [](codepen://introducing-jsx)
      We split JSX over multiple lines for readability. While it isn't required, when doing this, we also recommend wrapping it in parentheses to avoid the pitfalls of [automatic semicolon insertion](https://stackoverflow.com/q/2846283).
      ### JSX is an Expression Too {#jsx-is-an-expression-too}
      After compilation, JSX expressions become regular JavaScript function calls and evaluate to JavaScript objects.
      This means that you can use JSX inside of `if` statements and `for` loops, assign it to variables, accept it as arguments, and return it from functions:
      ```js{3,5}
      function getGreeting(user) {
      if (user) {
      return <h1>Hello, {formatName(user)}!</h1>;
      }
      return <h1>Hello, Stranger.</h1>;
      }
      ```
      ### Specifying Attributes with JSX {#specifying-attributes-with-jsx}
      You may use quotes to specify string literals as attributes:
      ```js
      const element = <div tabIndex="0"></div>;
      ```
      You may also use curly braces to embed a JavaScript expression in an attribute:
      ```js
      const element = <img src={user.avatarUrl}></img>;
      ```
      Don't put quotes around curly braces when embedding a JavaScript expression in an attribute. You should either use quotes (for string values) or curly braces (for expressions), but not both in the same attribute.
      >**Warning:**
      >
      >Since JSX is closer to JavaScript than to HTML, React DOM uses `camelCase` property naming convention instead of HTML attribute names.
      >
      >For example, `class` becomes [`className`](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) in JSX, and `tabindex` becomes [`tabIndex`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/tabIndex).
      ### Specifying Children with JSX {#specifying-children-with-jsx}
      If a tag is empty, you may close it immediately with `/>`, like XML:
      ```js
      const element = <img src={user.avatarUrl} />;
      ```
      JSX tags may contain children:
      ```js
      const element = (
      <div>
      <h1>Hello!</h1>
      <h2>Good to see you here.</h2>
      </div>
      );
      ```
      ### JSX Prevents Injection Attacks {#jsx-prevents-injection-attacks}
      It is safe to embed user input in JSX:
      ```js
      const title = response.potentiallyMaliciousInput;
      // This is safe:
      const element = <h1>{title}</h1>;
      ```
      By default, React DOM [escapes](https://stackoverflow.com/questions/7381974/which-characters-need-to-be-escaped-on-html) any values embedded in JSX before rendering them. Thus it ensures that you can never inject anything that's not explicitly written in your application. Everything is converted to a string before being rendered. This helps prevent [XSS (cross-site-scripting)](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks.
      ### JSX Represents Objects {#jsx-represents-objects}
      Babel compiles JSX down to `React.createElement()` calls.
      These two examples are identical:
      ```js
      const element = (
      <h1 className="greeting">
      Hello, world!
      </h1>
      );
      ```
      ```js
      const element = React.createElement(
      'h1',
      {className: 'greeting'},
      'Hello, world!'
      );
      ```
      `React.createElement()` performs a few checks to help you write bug-free code but essentially it creates an object like this:
      ```js
      // Note: this structure is simplified
      const element = {
      type: 'h1',
      props: {
      className: 'greeting',
      children: 'Hello, world!'
      }
      };
      ```
      These objects are called "React elements". You can think of them as descriptions of what you want to see on the screen. React reads these objects and uses them to construct the DOM and keep it up to date.
      We will explore rendering React elements to the DOM in the [next section](/docs/rendering-elements.html).
      >**Tip:**
      >
      >We recommend using the ["Babel" language definition](https://babeljs.io/docs/editors) for your editor of choice so that both ES6 and JSX code is properly highlighted.
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam egestas mauris condimentum tempor vulputate. Sed luctus cursus urna, eu ornare mi ullamcorper gravida. Sed et congue purus. Pellentesque eu turpis sit amet ligula malesuada condimentum quis vitae justo. Aenean mattis efficitur nisl. Aenean tortor leo, tempor a justo eget, tincidunt faucibus purus. Praesent at lacinia ligula. Proin lacus justo, finibus vehicula condimentum a, auctor eget tortor. Nam feugiat imperdiet lectus, sed pellentesque arcu facilisis et. Duis vel est lorem. Mauris varius lectus eget tincidunt lacinia.
      docs/article/viewing-ensembl-data.md
      + 1
      − 319
      View file @ c4434882
      ......@@ -5,322 +5,4 @@ status: published
      # Viewing Ensembl data
      The term ["render prop"](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce) refers to a technique for sharing code between React components using a prop whose value is a function.
      A component with a render prop takes a function that returns a React element and calls it instead of implementing its own render logic.
      ```jsx
      <DataProvider render={data => (
      <h1>Hello {data.target}</h1>
      )}/>
      ```
      Libraries that use render props include [React Router](https://reacttraining.com/react-router/web/api/Route/render-func), [Downshift](https://github.com/paypal/downshift) and [Formik](https://github.com/jaredpalmer/formik).
      In this document, we’ll discuss why render props are useful, and how to write your own.
      ## Use Render Props for Cross-Cutting Concerns {#use-render-props-for-cross-cutting-concerns}
      Components are the primary unit of code reuse in React, but it's not always obvious how to share the state or behavior that one component encapsulates to other components that need that same state.
      For example, the following component tracks the mouse position in a web app:
      ```js
      class MouseTracker extends React.Component {
      constructor(props) {
      super(props);
      this.handleMouseMove = this.handleMouseMove.bind(this);
      this.state = { x: 0, y: 0 };
      }
      handleMouseMove(event) {
      this.setState({
      x: event.clientX,
      y: event.clientY
      });
      }
      render() {
      return (
      <div style={{ height: '100vh' }} onMouseMove={this.handleMouseMove}>
      <h1>Move the mouse around!</h1>
      <p>The current mouse position is ({this.state.x}, {this.state.y})</p>
      </div>
      );
      }
      }
      ```
      As the cursor moves around the screen, the component displays its (x, y) coordinates in a `<p>`.
      Now the question is: How can we reuse this behavior in another component? In other words, if another component needs to know about the cursor position, can we encapsulate that behavior so that we can easily share it with that component?
      Since components are the basic unit of code reuse in React, let's try refactoring the code a bit to use a `<Mouse>` component that encapsulates the behavior we need to reuse elsewhere.
      ```js
      // The <Mouse> component encapsulates the behavior we need...
      class Mouse extends React.Component {
      constructor(props) {
      super(props);
      this.handleMouseMove = this.handleMouseMove.bind(this);
      this.state = { x: 0, y: 0 };
      }
      handleMouseMove(event) {
      this.setState({
      x: event.clientX,
      y: event.clientY
      });
      }
      render() {
      return (
      <div style={{ height: '100vh' }} onMouseMove={this.handleMouseMove}>
      {/* ...but how do we render something other than a <p>? */}
      <p>The current mouse position is ({this.state.x}, {this.state.y})</p>
      </div>
      );
      }
      }
      class MouseTracker extends React.Component {
      render() {
      return (
      <>
      <h1>Move the mouse around!</h1>
      <Mouse />
      </>
      );
      }
      }
      ```
      Now the `<Mouse>` component encapsulates all behavior associated with listening for `mousemove` events and storing the (x, y) position of the cursor, but it's not yet truly reusable.
      For example, let's say we have a `<Cat>` component that renders the image of a cat chasing the mouse around the screen. We might use a `<Cat mouse={{ x, y }}>` prop to tell the component the coordinates of the mouse so it knows where to position the image on the screen.
      As a first pass, you might try rendering the `<Cat>` *inside `<Mouse>`'s `render` method*, like this:
      ```js
      class Cat extends React.Component {
      render() {
      const mouse = this.props.mouse;
      return (
      <img src="/cat.jpg" style={{ position: 'absolute', left: mouse.x, top: mouse.y }} />
      );
      }
      }
      class MouseWithCat extends React.Component {
      constructor(props) {
      super(props);
      this.handleMouseMove = this.handleMouseMove.bind(this);
      this.state = { x: 0, y: 0 };
      }
      handleMouseMove(event) {
      this.setState({
      x: event.clientX,
      y: event.clientY
      });
      }
      render() {
      return (
      <div style={{ height: '100vh' }} onMouseMove={this.handleMouseMove}>
      {/*
      We could just swap out the <p> for a <Cat> here ... but then
      we would need to create a separate <MouseWithSomethingElse>
      component every time we need to use it, so <MouseWithCat>
      isn't really reusable yet.
      */}
      <Cat mouse={this.state} />
      </div>
      );
      }
      }
      class MouseTracker extends React.Component {
      render() {
      return (
      <div>
      <h1>Move the mouse around!</h1>
      <MouseWithCat />
      </div>
      );
      }
      }
      ```
      This approach will work for our specific use case, but we haven't achieved the objective of truly encapsulating the behavior in a reusable way. Now, every time we want the mouse position for a different use case, we have to create a new component (i.e. essentially another `<MouseWithCat>`) that renders something specifically for that use case.
      Here's where the render prop comes in: Instead of hard-coding a `<Cat>` inside a `<Mouse>` component, and effectively changing its rendered output, we can provide `<Mouse>` with a function prop that it uses to dynamically determine what to render–a render prop.
      ```js
      class Cat extends React.Component {
      render() {
      const mouse = this.props.mouse;
      return (
      <img src="/cat.jpg" style={{ position: 'absolute', left: mouse.x, top: mouse.y }} />
      );
      }
      }
      class Mouse extends React.Component {
      constructor(props) {
      super(props);
      this.handleMouseMove = this.handleMouseMove.bind(this);
      this.state = { x: 0, y: 0 };
      }
      handleMouseMove(event) {
      this.setState({
      x: event.clientX,
      y: event.clientY
      });
      }
      render() {
      return (
      <div style={{ height: '100vh' }} onMouseMove={this.handleMouseMove}>
      {/*
      Instead of providing a static representation of what <Mouse> renders,
      use the `render` prop to dynamically determine what to render.
      */}
      {this.props.render(this.state)}
      </div>
      );
      }
      }
      class MouseTracker extends React.Component {
      render() {
      return (
      <div>
      <h1>Move the mouse around!</h1>
      <Mouse render={mouse => (
      <Cat mouse={mouse} />
      )}/>
      </div>
      );
      }
      }
      ```
      Now, instead of effectively cloning the `<Mouse>` component and hard-coding something else in its `render` method to solve for a specific use case, we provide a `render` prop that `<Mouse>` can use to dynamically determine what it renders.
      More concretely, **a render prop is a function prop that a component uses to know what to render.**
      This technique makes the behavior that we need to share extremely portable. To get that behavior, render a `<Mouse>` with a `render` prop that tells it what to render with the current (x, y) of the cursor.
      One interesting thing to note about render props is that you can implement most [higher-order components](/docs/higher-order-components.html) (HOC) using a regular component with a render prop. For example, if you would prefer to have a `withMouse` HOC instead of a `<Mouse>` component, you could easily create one using a regular `<Mouse>` with a render prop:
      ```js
      // If you really want a HOC for some reason, you can easily
      // create one using a regular component with a render prop!
      function withMouse(Component) {
      return class extends React.Component {
      render() {
      return (
      <Mouse render={mouse => (
      <Component {...this.props} mouse={mouse} />
      )}/>
      );
      }
      }
      }
      ```
      So using a render prop makes it possible to use either pattern.
      ## Using Props Other Than `render` {#using-props-other-than-render}
      It's important to remember that just because the pattern is called "render props" you don't *have to use a prop named `render` to use this pattern*. In fact, [*any* prop that is a function that a component uses to know what to render is technically a "render prop"](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce).
      Although the examples above use `render`, we could just as easily use the `children` prop!
      ```js
      <Mouse children={mouse => (
      <p>The mouse position is {mouse.x}, {mouse.y}</p>
      )}/>
      ```
      And remember, the `children` prop doesn't actually need to be named in the list of "attributes" in your JSX element. Instead, you can put it directly *inside* the element!
      ```js
      <Mouse>
      {mouse => (
      <p>The mouse position is {mouse.x}, {mouse.y}</p>
      )}
      </Mouse>
      ```
      You'll see this technique used in the [react-motion](https://github.com/chenglou/react-motion) API.
      Since this technique is a little unusual, you'll probably want to explicitly state that `children` should be a function in your `propTypes` when designing an API like this.
      ```js
      Mouse.propTypes = {
      children: PropTypes.func.isRequired
      };
      ```
      ## Caveats {#caveats}
      ### Be careful when using Render Props with React.PureComponent {#be-careful-when-using-render-props-with-reactpurecomponent}
      Using a render prop can negate the advantage that comes from using [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) if you create the function inside a `render` method. This is because the shallow prop comparison will always return `false` for new props, and each `render` in this case will generate a new value for the render prop.
      For example, continuing with our `<Mouse>` component from above, if `Mouse` were to extend `React.PureComponent` instead of `React.Component`, our example would look like this:
      ```js
      class Mouse extends React.PureComponent {
      // Same implementation as above...
      }
      class MouseTracker extends React.Component {
      render() {
      return (
      <div>
      <h1>Move the mouse around!</h1>
      {/*
      This is bad! The value of the `render` prop will
      be different on each render.
      */}
      <Mouse render={mouse => (
      <Cat mouse={mouse} />
      )}/>
      </div>
      );
      }
      }
      ```
      In this example, each time `<MouseTracker>` renders, it generates a new function as the value of the `<Mouse render>` prop, thus negating the effect of `<Mouse>` extending `React.PureComponent` in the first place!
      To get around this problem, you can sometimes define the prop as an instance method, like so:
      ```js
      class MouseTracker extends React.Component {
      // Defined as an instance method, `this.renderTheCat` always
      // refers to *same* function when we use it in render
      renderTheCat(mouse) {
      return <Cat mouse={mouse} />;
      }
      render() {
      return (
      <div>
      <h1>Move the mouse around!</h1>
      <Mouse render={this.renderTheCat} />
      </div>
      );
      }
      }
      ```
      In cases where you cannot define the prop statically (e.g. because you need to close over the component's props and/or state) `<Mouse>` should extend `React.Component` instead.
      Curabitur in auctor urna, ac sollicitudin massa. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam pellentesque sem ac dictum finibus. Suspendisse iaculis scelerisque quam quis bibendum. Nullam augue felis, laoreet at laoreet vel, mattis sit amet risus. Aliquam imperdiet, enim ut feugiat egestas, augue odio mollis sapien, eu suscipit tellus ante et ligula.
      eleventy-site/articles.njk
      + 1
      − 0
      View file @ c4434882
      ......@@ -13,6 +13,7 @@ layout: default
      {{ article.body | safe }}
      </div>
      <div>
      <h1>Related video</h1>
      <iframe width="560" height="315" src="{{ article.data.relatedVideo.data.url }}" frameborder="0" allowfullscreen></iframe>
      {{ article.data.relatedVideo.body | safe }}
      </div>
      ......
      eleventy-site/css/styles.css
      + 11
      − 1
      View file @ c4434882
      a, a:visited, a:focus {
      color: blue;
      }
      .index-container {
      max-width: 800px;
      margin: auto;
      }
      .simple-article-container {
      max-width: 1000px;
      margin: auto;
      ......@@ -5,5 +14,6 @@
      .article-with-video-container {
      display: grid;
      grid-template-columns: 1fr 1fr;
      grid-template-columns: 1.5fr 1fr;
      grid-column-gap: 1rem;
      }
      eleventy-site/index.njk 0 → 100644
      + 19
      − 0
      View file @ c4434882
      ---
      layout: default
      ---
      <div class="index-container">
      <h1>
      Available articles
      </h1>
      <ul>
      {% for article in articles %}
      <li>
      <a href="/articles/{{ article.data.slug }}">{{ article.data.slug }}</a>
      </li>
      {% else %}
      <li>There are no articles</li>
      {% endfor %}
      </ul>
      </div>
      scripts/build-database/markdownImagePlugin.js
      + 1
      − 3
      View file @ c4434882
      ......@@ -12,10 +12,8 @@ const imageVisitor = (node) => {
      let host;
      if (process.env.NODE_ENV === 'production') {
      host = 'http://193.62.55.158:30799';
      } else {
      host = 'http://localhost:3000';
      node.url = `${host}${node.url}`;
      }
      node.url = `${host}${node.url}`;
      };
      module.exports = attacher;
      scripts/build-database/parseMarkdown.js
      + 1
      − 2
      View file @ c4434882
      const path = require('path');
      const vfile = require('to-vfile');
      const unified = require('unified');
      const parse = require('remark-parse');
      ......@@ -18,7 +17,7 @@ const parseMarkdown = async (pathToFile) => {
      .use(frontmatter, ['yaml', 'toml'])
      .use(extract, { yaml: yaml })
      .use(imagePlugin)
      .use(remark2rehype, {allowDangerousHTML: true})
      .use(remark2rehype, {allowDangerousHtml: true})
      .use(raw)
      .use(html)
      .process(vfile.readSync(pathToFile), function(err, file) {
      ......
      0% or .
      You are about to add 0 people to the discussion. Proceed with caution.
      Finish editing this message first!
      Please register or to comment