├── .gitbook.yaml ├── .gitignore ├── LICENSE ├── README.md └── tutorial ├── .gitbook.yaml ├── README.md ├── SUMMARY.md​ ├── checking-your-progress.md ├── part1-creating-a-custom-theme ├── README.md ├── connect-the-root-component-to-the-state.md ├── create-a-frontity-project.md ├── create-a-theme-package.md └── modify-the-root-component.md ├── part2-adding-a-menu ├── README.md └── use-the-link-component.md ├── part3-displaying-posts ├── README.md ├── display-posts-and-pages-separately.md ├── display-the-list-of-posts.md ├── display-the-post-content.md ├── formatting-the-date.md └── understanding-the-frontity-state.md ├── part4-adding-styling ├── README.md ├── add-dynamic-styling.md ├── global-styles.md ├── styled-components.md ├── styling-the-links.md └── styling-the-post-info.md ├── part5-adding-behaviour ├── README.md ├── add-pagination.md └── use-state-and-actions.md ├── part6-custom-post-types ├── README.md └── add-support-for-cpts.md ├── part7-finishing-touches ├── README.md ├── add-a-404-page.md ├── add-a-loading-component.md ├── other-things-to-do.md ├── seo-and-head-tags.md └── use-the-html2react-component.md ├── part8-deploying-the-project ├── README.md └── deploy-to-vercel.md └── part9-next-steps ├── README.md ├── contributing-to-frontity.md ├── getting-help-and-support.md └── learning-resources.md /.gitbook.yaml: -------------------------------------------------------------------------------- 1 | root: ./tutorial/ 2 | 3 | structure: 4 | readme: README.md 5 | summary: SUMMARY.md​ -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | toc.md 2 | tutorial/phrases.txt 3 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Frontity Documentation: Step by Step Tutorial 2 | 3 | Our documentation is distributed across three separate sites: 4 | 5 | | Docs Site | Repository | Description | 6 | | ------------------------------------------------------ | ------------------------------------------------- | --------------------------------- | 7 | | [docs.frontity.org](https://docs.frontity.org) | https://github.com/frontity/docs | Introduction, concepts and guides | 8 | | [api.frontity.org](https://api.frontity.org) | https://github.com/frontity/api-reference | API Reference | 9 | | [**tutorial.frontity.org**](https://tutorial.frontity.org) | https://github.com/frontity/step-by-step-tutorial | Step by Step guide | 10 | 11 | This repo corresponds to the step-by-step tutorial available at [**tutorial.frontity.org**](https://tutorial.frontity.org) 12 | 13 | ## What is Frontity? 14 | 15 | [Frontity](https://frontity.org/) is a free and [open source framework](https://github.com/frontity/frontity) to develop WordPress themes based on React. 16 | In other words, it allows to build a **React frontend** for a headless WordPress site, which serves its data via the WordPress REST API. 17 | 18 | ## What Does this Repository Contain? 19 | 20 | This repository contains: 21 | 22 | - [Tutorial Documentation](https://github.com/frontity/step-by-step-tutorial/tree/master/tutorial) - the source docs of the [Step by Step Tutorial for Frontity](https://tutorial.frontity.org/) 23 | 24 | ## How to Contribute 25 | 26 | Contributing to the Frontity documentation should be an enjoyable experience, as such we have created a set of [contributing guidelines](https://github.com/frontity/docs/tree/master/CONTRIBUTING.md) to help you do so. 27 | 28 | We have tried to make contributing to the Frontity documentation as easy as possible, especially for those new to Open Source. 29 | If anything is unclear or you have any questions then please use our [community forum](https://community.frontity.org/c/docs-and-tutorials/29) to discuss your contribution and how best to make it. 30 | 31 | ## License 32 | 33 | The Frontity documentation is an open source project released under the [Apache License 2.0](https://github.com/frontity/docs/tree/master/LICENSE.md). 34 | 35 | ## Get In Touch 36 | 37 | If you'd like to share your feedback or have any questions or suggestions regarding this documentation, feel free to reach out to us on our [community forum](https://community.frontity.org/c/docs-and-tutorials/29) 38 | 39 | There you will find both members of the community and staff who are happy to help answer questions on anything Frontity related. -------------------------------------------------------------------------------- /tutorial/.gitbook.yaml: -------------------------------------------------------------------------------- 1 | root: ./tutorial/ 2 | 3 | structure: 4 | readme: README.md 5 | summary: SUMMARY.md​ -------------------------------------------------------------------------------- /tutorial/README.md: -------------------------------------------------------------------------------- 1 | ⚠️ **Frontity Framework [is not under active development anymore.](https://frontity.org/blog/frontity-is-joining-automattic/)** 2 | 3 | **The team is now working on [the WordPress Interactivity API](https://make.wordpress.org/core/2024/03/04/interactivity-api-dev-note/). This unblocks the same UX Frontity framework enabled but directly in WordPress Core, fully compatible with the new Site Editor.** 4 | 5 | --- 6 | 7 | # Learn Frontity step-by-step 8 | 9 | ## Welcome to the Frontity step-by-step tutorial 10 | 11 | Hi, and a very warm welcome to the Frontity step-by-step tutorial. We're thrilled that you're interested in learning Frontity. 12 | 13 | The tutorial that you're about to embark on is a progressive sequence of lessons that will take you from first steps to mastery. 14 | 15 | Via a practical example project it will provide you with a solid foundation in developing websites with Frontity and give you the knowledge you need to work with Frontity on your own projects. It will also arm you with the concepts and knowledge you need to better understand the other documentation resources: 16 | 17 | - [**docs.frontity.org**](https://docs.frontity.org) - Introduction, concepts and guides 18 | - [**api.frontity.org**](https://api.frontity.org) - API Reference 19 | 20 | Since this is a progressive tutorial we recommend that you follow the lessons in sequence, as each lesson builds on what was learned earlier. 21 | 22 | ### Prerequisites 23 | 24 | Frontity is built on React. You should therefore feel comfortable working with JavaScript, and have at least some familiarity with React and also with ES6. 25 | 26 | {% hint style="info" %} 27 | If you need to get up to speed, or if you need a refresher, there are introductions to the basics of both **[JavaScript](https://docs.frontity.org/guides/javascript-basics)** and **[React](https://docs.frontity.org/guides/react-basic)** in the documentation. If you've worked through those guides, or if you're already comfortable with the concepts explained there, then you're good to go. 👌 28 | {% endhint %} 29 | 30 | An understanding of HTML and CSS is also assumed, as is a familiarity with the command line. 31 | 32 | You will need to have [node.js](https://nodejs.org/) installed on your development machine. You will, of course, also need a web browser and a code editor/IDE. 33 | 34 | No previous knowledge or understanding of Frontity is required. This step-by-step tutorial starts you off with the very basics. 35 | 36 | ### The project 37 | 38 | Our project for this step-by-step tutorial will be to build a fully working Frontity theme, starting from scratch. 39 | 40 | {% hint style="info" %} 41 | Frontity provides two themes to get you started, `mars-theme` and `twentytwenty`, and there are a host of third party themes on [_npmjs.com_](https://www.npmjs.com/search?q=keywords:frontity-theme) that you can install into your Frontity project. 42 | 43 | One of these could well fit your needs, but the best way to really gain an understanding of Frontity and how it works is to build your own theme. 44 | {% endhint %} 45 | 46 | We'll start at ground level by installing Frontity, then go on to create a theme package which we will then develop into a fully working and functional theme. 47 | 48 | Along the way we'll cover a number of different topics, from listing posts, to displaying posts and pages, to styling our project and adding interactivity. We'll even make our project SEO friendly, refine it with some finishing touches, and make it work with Custom Post Types. 49 | 50 | We will be there by your side guiding you through every step, right through to ultimately deploying our finished project to a live server. 51 | 52 | {% hint style="info" %} 53 | 👀 We'd really like you to see the project develop as you progress through the tutorial, so we're certainly not encouraging you to do this, but if you really **do** want to take a sneak peak at the finished project the final version can be seen in [this CodeSandbox](https://codesandbox.io/s/github/frontity-demos/tutorial-hello-frontity). 54 | {% endhint %} 55 | 56 | By the end of this tutorial you'll be a Frontity ninja! 🥷 57 | 58 | Let's go! 👉 59 | -------------------------------------------------------------------------------- /tutorial/SUMMARY.md​: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | 3 | * [👋 Welcome](README.md) 4 | * [✔ Checking your progress](checking-your-progress.md) 5 | * [1️⃣ Creating a custom theme](part1-creating-a-custom-theme/README.md) 6 | * [Create a Frontity Project](part1-creating-a-custom-theme/create-a-frontity-project.md) 7 | * [Create a Theme Package](part1-creating-a-custom-theme/create-a-theme-package.md) 8 | * [Modify the `` component](part1-creating-a-custom-theme/modify-the-root-component.md) 9 | * [Connect the `` component to the state](part1-creating-a-custom-theme/connect-the-root-component-to-the-state.md) 10 | * [2️⃣ Adding a menu](part2-adding-a-menu/README.md) 11 | * [Use the `` component](part2-adding-a-menu/use-the-link-component.md) 12 | * [3️⃣ Displaying posts](part3-displaying-posts/README.md) 13 | * [Understanding the Frontity state](part3-displaying-posts/understanding-the-frontity-state.md) 14 | * [Display the list of posts](part3-displaying-posts/display-the-list-of-posts.md) 15 | * [Display the post content](part3-displaying-posts/display-the-post-content.md) 16 | * [Display posts and pages separately](part3-displaying-posts/display-posts-and-pages-separately.md) 17 | * [Formatting the date](part3-displaying-posts/formatting-the-date.md) 18 | * [4️⃣ Adding styling](part4-adding-styling/README.md) 19 | * [Global styles](part4-adding-styling/global-styles.md) 20 | * [Styled components](part4-adding-styling/styled-components.md) 21 | * [Styling the links](part4-adding-styling/styling-the-links.md) 22 | * [Styling the post info](part4-adding-styling/styling-the-post-info.md) 23 | * [Add dynamic styling](part4-adding-styling/add-dynamic-styling.md) 24 | * [5️⃣ Adding behaviour](part5-adding-behaviour/README.md) 25 | * [Use 'state' and 'actions'](part5-adding-behaviour/use-state-and-actions.md) 26 | * [Add pagination](part5-adding-behaviour/add-pagination.md) 27 | * [6️⃣ Custom Post Types](part6-custom-post-types/README.md) 28 | * [Add support for Custom Post Types](part6-custom-post-types/add-support-for-cpts.md) 29 | * [7️⃣ Finishing touches](part7-finishing-touches/README.md) 30 | * [Add a `` component](part7-finishing-touches/add-a-loading-component.md) 31 | * [Add a 404 page](part7-finishing-touches/add-a-404-page.md) 32 | * [Use the `` component](part7-finishing-touches/use-the-html2react-component.md) 33 | * [SEO and head tags](part7-finishing-touches/seo-and-head-tags.md) 34 | * [Other things to do](part7-finishing-touches/other-things-to-do.md) 35 | * [8️⃣ Deploying the project](part8-deploying-the-project/README.md) 36 | * [Deploy to Vercel](part8-deploying-the-project/deploy-to-vercel.md) 37 | * [9️⃣ Next Steps](part9-next-steps/README.md) 38 | * [Learning resources](part9-next-steps/learning-resources.md) 39 | * [Getting help and support](part9-next-steps/getting-help-and-support.md) 40 | * [Contributing to Frontity](part9-next-steps/contributing-to-frontity.md) 41 | -------------------------------------------------------------------------------- /tutorial/checking-your-progress.md: -------------------------------------------------------------------------------- 1 | # Checking your progress 2 | 3 | We wanted to make the learning experience as straightforward and frictionless as possible for you, so we've included a way for you to check that your version of the project is correct at each and every stage of the tutorial as you work through it. 4 | 5 | We've already drawn your attention to the finished project on CodeSandBox, but the final version of the code is not necessarily the best resource to refer to if at any particular stage your code isn't working as expected, or if you're getting errors in the terminal or in the browser console. 6 | 7 | So, for each step in this tutorial we have created a commit in [this repo](https://github.com/frontity-demos/tutorial-hello-frontity) with just the changes made in that step. 8 | 9 | If you get stuck at any point then you can compare your code at the relevant stage to [the tagged commits in the repo](https://github.com/frontity-demos/tutorial-hello-frontity/tags). 10 | 11 | To view the differences ([diffs](https://en.wikipedia.org/wiki/Diff)) at that stage you can click the link as highlighted in the screengrab below: 12 | 13 |

14 | A tagged commit on GitHub 15 |

16 | 17 | In case you're not familiar with viewing diffs in a repo, you'll see something like this: 18 | 19 |

20 | Viewing the diffs in a commit on GitHub 21 |

22 | 23 | > Lines with a 🔴 red background marked with a minus sign ➖ are removed at that step. 24 | 25 | > Lines with a 🟢 green background marked with a plus sign ➕ are added at that step. 26 | 27 | > Sometimes lines are newly added or totally removed, but quite often an added line is a modified version of the removed line. For example, in the screengrab above, line 2 and line 8 are new but all other added lines are a modified replacement for the removed line above it. 28 | 29 | You can also download the code completed up to a particular step by using the `zip` or `tar.gz` links for that tagged commit. 30 | 31 |

32 | Download links for a tagged commit on GitHub 33 |

34 | 35 | If you are on a tag page you can compare the changes between that step and any other arbitrarily selected step by using the 'Compare' button. 36 | 37 |

38 | The 'Compare' button allows you to compare this step with any other 39 |

40 | 41 | At the end of each lesson (and sometimes within a lesson) you will see a box like this one with a link going directly to the commit that has the changes in that lesson (or that part of the lesson): 42 | 43 |

44 | Check your code at the end of each step. 45 |

46 | -------------------------------------------------------------------------------- /tutorial/part1-creating-a-custom-theme/README.md: -------------------------------------------------------------------------------- 1 | # Creating a custom theme 2 | 3 | We'll start our journey to Frontity mastery by setting Frontity up from the command line. 4 | 5 | We will then create a theme package and go on to take our first baby steps in customising our new theme and accessing Frontity's 'state'. 👶 6 | 7 | {% hint style="info" %} 8 | ☝️ Remember this step-by-step tutorial is progressive and each lesson builds on what was learned before. You should therefore work through the tutorial in the order in which it is presented. 9 | {% endhint %} 10 | -------------------------------------------------------------------------------- /tutorial/part1-creating-a-custom-theme/connect-the-root-component-to-the-state.md: -------------------------------------------------------------------------------- 1 | # Connect the `` component to the state 2 | 3 | Let’s now connect the `` component to the Frontity state using `connect`. 4 | 5 | `connect` is a higher order component that takes a React component as an argument. It passes the Frontity object to the React component specified in the argument via props. The Frontity object has amongst its properties `state`, `actions` and `libraries`. `connect` therefore enables a component in our theme to access data stored in the `state`, or functions available in `actions`. 6 | 7 | This also ensures that the component is re-rendered whenever any value from the state which the component is using is changed. 8 | 9 | {% hint style="info" %} 10 | We'll be covering the Frontity state in detail shortly in the section entitled [Understanding the Frontity state](../part3-displaying-posts/understanding-the-frontity-state.md). 11 | {% endhint %} 12 | 13 | In order to connect our component to the Frontity state we need to `import { connect } from "frontity"`, pass `state` as a (destructured) prop to our component, and finally export the connected component with `export default connect(Root)`. 14 | 15 | We can check that our `` component is connected to the state by adding a `

` element to our component to display the URL we are currently in. We can do this by using `state.router.link`. 16 | 17 | ```jsx 18 | // File: /packages/my-first-theme/src/components/index.js 19 | 20 | import React from "react" 21 | import { connect } from "frontity" 22 | 23 | const Root = ({ state }) => { 24 | return ( 25 | <> 26 |

Frontity Workshop

27 |

Current URL: {state.router.link}

28 | 29 | ) 30 | } 31 | 32 | export default connect(Root) 33 | ``` 34 | 35 | Now when you save the file we can see that we are in the root of our site: `/`. 36 | 37 |

38 | Frontity in the browser 39 |

40 | 41 | You can try changing the URL in the browser's address bar to something like http://localhost:3000/about-us to see how the value of `state.router.link` changes. 42 | 43 |

44 | Frontity in the browser 45 |

46 | 47 | {% hint style="success" %} 48 | **Check you're on the right track** by comparing your changes with [the ones in this commit](https://github.com/frontity-demos/tutorial-hello-frontity/commit/eebb495ba16ede2d310bc838396aca662df5f3bc). 49 | {% endhint %} 50 | -------------------------------------------------------------------------------- /tutorial/part1-creating-a-custom-theme/create-a-frontity-project.md: -------------------------------------------------------------------------------- 1 | # Create a Frontity Project 2 | 3 | The first thing we are going to do is create a new Frontity project. As it's our first time exploring Frontity let's call our project "hello-frontity". 4 | 5 | To create the project, open up your terminal, navigate to the directory where you want to install your new project, and run this command: 6 | 7 | ```bash 8 | npx frontity create hello-frontity 9 | ``` 10 | 11 | When prompted select the `mars-theme` - it's the basic starter theme that we recommend for beginners. 12 | 13 | {% hint style="info" %} 14 | We won't be using `mars-theme`, we will instead be using the custom theme that we will build over the course of this tutorial, but you need to select a theme during the setup process. 15 | {% endhint %} 16 | 17 | When the install process finishes, you will have a new sub-directory called `hello-frontity` containing your project’s code. The structure of the project will look something like this: 18 | 19 |

20 | Frontity project structure 21 |

22 | 23 | {% hint style="info" %} 24 | Apart from defining the configuration of our project almost all of our time will be spent working in the `packages` directory. 25 | 26 | The `node_modules` directory is where all our dependencies are stored. You won't need to modify or open any of the files inside this directory. The `build` directory is where the final deployment build of our project will live. 27 | 28 | Other files such as `package.json` and `package-lock.json` are project configuration files and you shouldn't have any need to touch them either. 29 | {% endhint %} 30 | 31 | Let's take a look at the file `frontity.settings.js`. This is the configuration file for our project and can be found in the root directory of the project. One of the elements that you'll see here is an array of `packages`. In Frontity everything is a package, including the theme, so one of the packages in the array is `@frontity/mars-theme`. We'll be replacing this in the next lesson. 32 | 33 | Another package in the array is `@frontity/wp-source`. This has a property: `state.source.url`. This is where you define the WordPress site that you want to connect to in order to get data from the REST API. Changing this is one of the first things you would normally do when configuring a Frontity project, but let's leave this as it is since this is the source for the data that we are going to be working with during this tutorial. 34 | 35 | ```js 36 | // File: /frontity.settings.js 37 | 38 | // ... 39 | { 40 | name: "@frontity/wp-source",dir 41 | state: { 42 | source: { 43 | url: "https://test.frontity.org", 44 | }, 45 | }, 46 | } 47 | ``` 48 | 49 | Now that we have our Frontity project set up and we've had a good old poke around to see how it's structured and configured let's test that everything is working. 50 | 51 | Change into the project directory and start a development server: 52 | 53 | ```bash 54 | cd hello-frontity 55 | npx frontity dev 56 | ``` 57 | 58 | {% hint style="info" %} 59 | `npx` downloads an npm package to run just this one time and then removes it from your computer - [learn more here](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b). 60 | {% endhint %} 61 | 62 | A new browser tab should open automatically for you. If it didn't then open `http://localhost:3000` in your browser. 63 | 64 | You should now see your first Frontity project. At the moment it's using the "starter theme" that we selected earlier, i.e. `@frontity/mars-theme`, and it is connected to our test WordPress site (i.e. https://test.frontity.org as defined in `frontity.settings.js` at `state.source.url`) which you will see contains a travel blog as its content. 65 | 66 | In the next step we'll start creating our own Frontity theme. 67 | -------------------------------------------------------------------------------- /tutorial/part1-creating-a-custom-theme/create-a-theme-package.md: -------------------------------------------------------------------------------- 1 | # Create a Theme Package 2 | 3 | As stated previously, rather than using the default starter theme that we selected during the setup process (i.e. `@frontity/mars-theme`) we are instead going to develop a custom theme from scratch. To do this we need to create a new package for our theme's code. As it's our first ever theme let's call our theme "my-first-theme". 4 | 5 | > **NOTE:** Before continuing you may need to stop the dev server process that we ran previously with _CONTROL+C_. 6 | 7 | To create a package run the following command in the terminal: 8 | 9 | ```bash 10 | > npx frontity create-package my-first-theme 11 | ``` 12 | 13 | You will be prompted to specify the namespace to use. Since you are creating a theme you can use the default `theme`, so you can just press _Enter_ at this point. 14 | 15 |

16 | Creating a package 17 |

18 | 19 | When the process is complete you will have a new directory called `/packages/my-first-theme`. This is where we will be doing most of our work to build the theme. 20 | 21 |

22 | Structure of a newly created package 23 |

24 | 25 | The first thing we'll do is to remove `@frontity/mars-theme` from our settings and replace it with `my-first-theme`. 26 | 27 | Remove the following from the file `frontity.settings.js`: 28 | 29 | ```js 30 | // File: /frontity.settings.js 31 | 32 | { 33 | name: "@frontity/mars-theme", 34 | state: { 35 | theme: { 36 | menu: [ 37 | ["Home", "/"], 38 | ["Nature", "/category/nature/"], 39 | ["Travel", "/category/travel/"], 40 | ["Japan", "/tag/japan/"], 41 | ["About Us", "/about-us/"] 42 | ], 43 | featured: { 44 | showOnList: false, 45 | showOnPost: false 46 | } 47 | } 48 | } 49 | }, 50 | ``` 51 | 52 | And replace it with: 53 | 54 | ```js 55 | // File: /frontity.settings.js 56 | 57 | { 58 | name: "my-first-theme" 59 | }, 60 | ``` 61 | 62 | We've now told Frontity to use our new theme rather than "mars-theme". Save the file and then run this command again: 63 | 64 | ```bash 65 | > npx frontity dev 66 | ``` 67 | 68 | If you see this in your browser then everything is working. Hooray! 🙌 69 | 70 |

71 | Frontity in the browser 72 |

73 | 74 | {% hint style="success" %} 75 | **Check you're on the right track** by comparing your changes with [the ones in this commit](https://github.com/frontity-demos/tutorial-hello-frontity/commit/7733a6c3d9886cf4a86397e8ba1a668fcd3cb928). 76 | {% endhint %} 77 | -------------------------------------------------------------------------------- /tutorial/part1-creating-a-custom-theme/modify-the-root-component.md: -------------------------------------------------------------------------------- 1 | # Modify the `` component 2 | 3 | Let's continue by taking our initial baby steps in getting Frontity to display the content we want. 4 | 5 | Modify the `` component in the `/packages/my-first-theme/src/index.js` file so that it returns an `

` element containing the text “Hello Frontity". 6 | 7 | ```jsx 8 | // File: /packages/my-first-theme/src/index.js 9 | 10 | const Root = () => { 11 | return ( 12 | <> 13 |

Hello Frontity

14 | 15 | ) 16 | } 17 | ``` 18 | 19 | Once you save the file you should see the content in the browser change. 20 | 21 | {% hint style="info" %} 22 | Webpack watches for changes in the `/packages` directory and refreshes the browser if it detects any changes. Since we have changed the content of a file within the `/packages` directory the content in the browser should automatically update. 23 | {% endhint %} 24 | 25 | {% hint style="success" %} 26 | **Check you're on the right track** by comparing your changes with [the ones in this commit](https://github.com/frontity-demos/tutorial-hello-frontity/commit/7ba7b0879bb02240c6bf627a4f15c50ba249726b). 27 | {% endhint %} 28 | 29 | It would be convenient, and make our codebase cleaner and more logical, and hence our future development much easier, if all our React components were placed together in a single directory. So, let's move the `` component into its own file which we'll put in a separate directory. 30 | 31 | Create a new directory called `components` inside `/packages/my-first-theme/src`. This is where we will create all the component files for our theme. Then, inside `/packages/my-first-theme/src/components` create a new file called `index.js`. 32 | 33 | Add the following code to the new file _(which we will henceforth refer to as the 'root component' file to distinguish it from the other `index.js` file in the `src` directory one level below in the structure)_. 34 | 35 | ```jsx 36 | // File: /packages/my-first-theme/src/components/index.js 37 | 38 | import React from "react" 39 | 40 | const Root = () => { 41 | return ( 42 | <> 43 |

Hello Frontity

44 | 45 | ) 46 | } 47 | 48 | export default Root 49 | ``` 50 | 51 | You will see that this is the same `` component as before but moved into the new file and then exported. We also need to import React into our new file. 52 | 53 | We now need to import the component into the file `/packages/my-first-theme/src/index.js` which you can modify as follows: 54 | 55 | ```jsx 56 | // File: /packages/my-first-theme/src/index.js 57 | 58 | import Root from "./components" 59 | 60 | const myFirstTheme = { 61 | name: "my-first-theme", 62 | roots: { 63 | theme: Root, 64 | }, 65 | state: { 66 | theme: {}, 67 | }, 68 | actions: { 69 | theme: {}, 70 | }, 71 | } 72 | 73 | export default myFirstTheme 74 | ``` 75 | 76 | Save both files and make a quick check to see that everything is still working in the browser. 77 | 78 | {% hint style="success" %} 79 | **Check you're on the right track** by comparing your changes with [the ones in this commit](https://github.com/frontity-demos/tutorial-hello-frontity/commit/88e834628e3e4a66676425b45314f98e0046c3c2). 80 | {% endhint %} 81 | -------------------------------------------------------------------------------- /tutorial/part2-adding-a-menu/README.md: -------------------------------------------------------------------------------- 1 | # Adding a menu 2 | 3 | We've now got the beginnings of our project up and running and we've created the directory structure that we're going to work in going forward. 4 | 5 | We've also seen how we can change the value stored in `state.router.link` by manually changing the URL in the browser's address bar. 6 | 7 | In this second section we will create a basic menu consisting of a series of links that ultimately will enable us to navigate around our site, but for now will change the URL (and hence the value stored in `state.router.link`) for us. 8 | 9 | To do so we will learn about and use one of the built-in components that Frontity provides, i.e. the `` component. 10 | -------------------------------------------------------------------------------- /tutorial/part2-adding-a-menu/use-the-link-component.md: -------------------------------------------------------------------------------- 1 | # Use the `` component 2 | 3 | In the last lesson we saw that `state.router.link` stores the current URL. We demonstrated this by manually changing the URL in the browser's address bar and saw how the URL in our `

` element changed as the component reacted to the data change. 4 | 5 | In this lesson we will create a menu-based navigation to change the URL for us. 6 | 7 | Frontity provides a number of useful components for us, amongst which is the `` component. The simplest way to use it is to just provide a `link` attribute with the URL as its value: 8 | 9 | ```jsx 10 | Home 11 | ``` 12 | 13 | We also provide the string that we want to be displayed as a clickable link. In the example above that is 'Home'. 14 | 15 | The `` component simply outputs an `` element into the resulting HTML, but without forcing a page reload which is what would occur if you simply added an `` element instead of using the `` component. 16 | 17 | ```html 18 | Home 19 | ``` 20 | 21 | Before we can use any of Frontity's built-in components we first need to import it. Frontity's built-in components are imported from `@frontity/components`. 22 | 23 | So let's import the `` component into our root component file for use within our `` component. Let's add this import statement as the third line: 24 | 25 | ```jsx 26 | import Link from "@frontity/components/link" 27 | ``` 28 | 29 | With that done we are now in a position to add a menu consisting of a `