inu-v2-b

A photo portfolio theme with React and WordPress.

Contents

• Prerequisites
• Requirements
• Deliverables
• Features
  • Backend
  • Frontend
  • Design
• Development process
  • Mocks - v0.0.1
  • Static content (a.k.a data)- v0.0.2
  • Interaction - v0.0.3
  • Refactoring - v0.0.4
  • Theme - v0.0.5
  • Performance - v0.0.6
  • Best practices checklist - v0.0.7
  • Documentation - v0.0.8
  • Live Test - v0.0.9
• Results
  • The old site look
  • The new site look
  • The old site performance
  • The new site performance
• Known issues
• Changelog
  • [0.1.2] - 2019-08-12
  • [0.1.1] - 2019-08-06
  • [0.1.0] - 2019-08-01

Prerequisites

The old inu.ro design is dated back spring 2014. It's time for a refresh.

The slider on mobile screens was confusing: on click the slide disappeared and the next photo was sliding in. This had to be fixed.

Requirements

1. Keep the same simple design.
2. Keep the black/white background switcher.
3. Fix the slider on mobile screens.
4. Add a random slideshow.
5. Make categories display order changeable on the backend.
6. Keep the WordPress backend.
7. Refresh the front-end stack and make it future friendly for another couple of years.
8. Enhance page load performance.

Deliverables

• The new site: http://inu.ro
• The source code: https://github.com/metamn/inu-v2-b
• The styleguide: http://inu.ro/styleguide
• The component guide and the API documentation: http://metamn.io/inu-v2-b/
• A blog post: http://metamn.io/react/thoughts-on-react-after-the-first-commercial-project/

Features

The following features were added:

Backend

• WordPress updated to Gutenberg.
• Category Order and Taxonomy Terms Order plugin added.
• Support for multiple ways to add photos:
  • As a featured image.
  • Inserted into the post.
  • As associated media to the post.

Frontend

• React Single Page Application with function components and hooks.
• WordPress theming with create-react-wptheme
• GraphQL with WP GraphQL and @apollo/react-hooks
• styled-components for styling.
• Prop types for static type checking.
• Query fragments.
• Complete API/JSDoc documentation.

Design

• Component based design with Storybook.

• Design documentation with a custom made styleguide.

• New technologies wherever possible:

  • CSS Grid layout
  • CSS scroll-snap for sliding images inspired by Google Developers

Development process

A short overview of the major steps and tasks done. It is completely based on Thinking in React with each step separated into a feature branch. Every branch goes into deeper details in its README.md.

Mocks - v0.0.1

1. Mocking up the component structure and the functionality
2. Adjusting component structure to the WP GraphQL API
3. Applying the single responsibility principle
4. Create requirement specification

Static content (a.k.a data)- v0.0.2

1. Building up the data components.
2. Continuing with other (presentational) components.
3. Creating additional components when necessary. Like MenuItem for Menu.
4. Focusing on content and data. Any new ideas are added as Github Issues to be implemented later.

Interaction - v0.0.3

1. Going through each component which is handling interactive elements and implement their functionality. Usually with states.
2. Connect states together and lifting state up.

Refactoring - v0.0.4

1. Make sure all components satisfy the Single Responsibility Principle (SRP).
2. Separate reusable components (for web, for WordPress) from project specific components.

Theme - v0.0.5

1. Presentational (reusable web) components should be semantically valid in the W3C checker.
2. Container (non-reusable, project specific) components which holds the business logic should be fragments. This way the divism is highly reduced and the layout can be easily sketched with CSS Grid.
3. All elements should be aligned to the typographic grid both vertically and horizontally.

Performance - v0.0.6

1. Database queries were lifted up to the highest level. This way the minimum amount of queries are performed only.
2. A new slider had to be added. The old slider triggered too many re-renders.

Best practices checklist - v0.0.7

1. Testing the dev version only. After deployment the live (staging) site will be more thoroughly tested.

Documentation - v0.0.8

1. Developer docs created (this README.md).
2. Components documented with Storybook.
3. API documented with JSDoc, JSDoc2Markdown and added to Storybook as Notes.
4. Theme / style / design decisions documented with a handmade styleguide.

Live Test - v0.0.9

1. Testing live on multiple devices and browsers.

| Device / OS | iOS *| Android *| Ubuntu *| Windows *| MacOS *|
---------------------------------------------------------------
| Phone       | [1]  | 🆗       | n/a     | n/a      | n/a     |
| Tablet      | [1]  | 🆗       | n/a     | n/a      | n/a     |
| Desktop     | n/a  | n/a      | 🆗      | [2]      | ...     |

[1] The slider flicks on touch scroll. This is an [official bug](https://github.com/metamn/inu-v2-b/issues/24)

[2] Doesn't works at all in Internet Explorer.

🆗 Works in:
* iOS browsers: Safari
* Android browsers: Chrome
* Ubuntu browsers: Firefox, Chrome, Opera
* Windows browsers: Chrome, Firefox, Edge

2. Re-testing for best practices.

See screenshots below with results.

Performance - v0.1.2

Implement best practices (continuously collected) to enhance performance. Such:

1. Wrap all business logic into a UseEffect

2. Wrap expensive function calls into useMemo

3. Stress-test the whole app: https://overreacted.io/writing-resilient-components/#principle-3-no-component-is-a-singleton

4. Avoid making a local state global: https://overreacted.io/writing-resilient-components/#principle-4-keep-the-local-state-isolated

5. Reduce re-renders

Couldn't manage it. All examples 1 2 are using the async / axios way which isn't compatible with the useQuery approach from Apollo where a loading result is immediately returned - which cannot be memoized, set as state etc ...

Still to research ... the solution lies somewhere in apolloClient / <ApolloProvider>

6. Suspense

The functionality is already implemented either by displaying default data (Site info, Categories) or with the fade in technique (Content) and works pretty well ...

Results

The old site look

The new site look

The old site performance

The new site performance

Known issues

• Safari / iOS scroll bug: #24

Changelog

All changes to the project are documented here using the Keep a Changelog format and semantic versioning.

[0.1.2] - 2019-08-12

Added

• A few memoizations where they were appropiate.

Changed

• react-apollo-hooks to @apollo/react-hooks

Fixed

• Grouping images into '/images'. See #31

[0.1.1] - 2019-08-06

Fixed

• Storybook issue #26

[0.1.0] - 2019-08-01

This is the first official release.