You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: guides/Building-Regulations-locally.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Building Regulations Locally
3
3
layout: default
4
-
parent: Wiki Imports
4
+
parent: Guides
5
5
---
6
6
7
7
This page aims to guide you through the process of building the WCA Regulations and Guidelines, which is something that you may want to do when you first clone the website repository.
This documentation is very new, so you should feel free to suggest changes.
8
+
9
+
## Preamble
10
+
11
+
The website is historically purely Rails, with a lot of jquery to handle user interaction.
12
+
With the integration of Webpack to Rails, we started migrated our javascript and css codebase to Webpack,
13
+
but it's still very much in progress.
14
+
This means we serve our assets from two sources: sprockets (assets located in '/assets'), and webpack (assets located in '/packs').
15
+
16
+
New javascript developments should occur with webpack.
17
+
18
+
Packs can import javascript, stylesheets, or even images (Webpack will figure
19
+
out the dependencies and what to include when).
20
+
21
+
## Creating a new component
22
+
23
+
Let's assume you want to write a new component to display the website posts,
24
+
and you want to name it `PostsWidget`.
25
+
26
+
All of our components live under the aptly named folder `app/webpacker/components`.
27
+
You are essentially free to write your code there as you please, but please consider the following as rule of thumb: If it's a simple component that resides within one file, just create it as `PostsWidget.js` and have fun. If it's a complex setup with multiple interacting files, create a folder `components/PostsWidget` and create an `index.js` and other `js` files in there.
28
+
29
+
The `index.js[x]` file should contain the main component you want to export,
30
+
and declare itself in a manner that would work for normal pure-JS projects (i.e. `export`ing the component you want to use in Rails):
Now that we have a very basic component exported, we most likely want to include
48
+
it in some page of the website.
49
+
Once you've found a view where to include your component, you will have to:
50
+
- tell the website you'll need the component
51
+
- render the component somewhere
52
+
53
+
There is an application helper for that:
54
+
-`react_component` will let you emit a registered component.
55
+
56
+
In our case, assuming we want to use the widget on the posts index page,
57
+
the `app/views/posts/index.html.erb` file would look like this:
58
+
```erb
59
+
<div class="container">
60
+
<%= react_component("PostsWidget", {
61
+
msg: "Hello world!",
62
+
}, {
63
+
id: "posts_widget",
64
+
}) %>
65
+
</div>
66
+
```
67
+
68
+
The first mandatory argument to `render_react_component` is the name of the component,
69
+
the same name used in the JS `export` (actually, there is a JavaScript `require` context running under the hood, so it's literally doing JS `require` with whatever name you pass it).
70
+
The second argument is a keyword dict directly containing the properties you want to pass to the component.
71
+
The third, optional argument is a keyword dict with other HTML options. For example, `id` may be used to set a specific
72
+
id on the `div` holding the component.
73
+
74
+
In our example we use it to set the `msg` property.
75
+
76
+
77
+
## Writing UI
78
+
79
+
Writing a message may be fun, but it doesn't go very far.
80
+
We recently switched to [Fomantic UI (FUI)](https://fomantic-ui.com/) (which you may also know as Semantic UI)
81
+
as our main framework, it has React bindings through the `semantic-ui-react` package.
82
+
Documentation for all usable components is [here](https://react.semantic-ui.com/).
83
+
84
+
Basically if you want to include some components from FUI you would do something like that:
85
+
```
86
+
import {
87
+
Button, Card, Icon, List, Pagination,
88
+
} from 'semantic-ui-react';
89
+
```
90
+
91
+
We don't import the whole FUI CSS by default.
92
+
If you're using some components that were not already used by the website, make sure to edit our [global_style.js](https://github.com/thewca/worldcubeassociation.org/blob/0d0137379b5ce1a62e05f0a4dc390fef7aa8292e/WcaOnRails/app/webpacker/packs/global_styles.js) to include the CSS-es relevant to these components.
93
+
If what you're using is extremely specific to the widget you're writing, you may consider only including the style in your widget's javascript file.
94
+
95
+
If you want to write custom (S)CSS that would be active only when that component is used, you can create a custom (s)css file in the same folder of your component and import it. Webpack will automatically include the style when loading the pack containing your component (again, see the real `posts_widget` example :)).
96
+
97
+
I won't go much more in details as the rest is just putting together React
98
+
components, which is not the scope of that documentation.
99
+
100
+
101
+
## Loading data from the website
102
+
103
+
Chances are that your new component will want to load some data from the website.
104
+
In the case of our `PostsWidget`, we would like to get the list of posts, to display them.
105
+
While we're using React to create the *View* for them, the *Model* and *Controller*
106
+
part are handled by Rails.
107
+
108
+
Therefore we'll need:
109
+
- to make rails give us the list of posts
110
+
- somehow load them asynchronously in our component.
111
+
112
+
### Making the server send json data
113
+
114
+
The first part is achieved by making the `index` method of the `posts_controller`
115
+
reply to us with a json containing the posts data.
116
+
Here is roughly what it could look like:
117
+
```ruby
118
+
defindex
119
+
respond_to do |format|
120
+
format.json do
121
+
render json: {
122
+
posts:Post.visible.order(created_at::desc),
123
+
}
124
+
end
125
+
format.html do
126
+
render :index
127
+
end
128
+
end
129
+
end
130
+
```
131
+
132
+
It basically tells rails to:
133
+
- if the client request json, render the visible posts as json, sorted with the most recent first
134
+
- if the client request html (as it would by visiting the index page), we just
135
+
render the html page without loading any data (because it will render the component
136
+
which itself will request the data as json).
137
+
138
+
You can see the actual implementation of that endpoint (with extra options as which
139
+
page to load, how many posts to load, ...) in `app/controller/posts_controller.rb`.
140
+
141
+
### Using these data in our component
142
+
143
+
Now that we have an endpoint to fetch data from, we need to use it from our component.
144
+
We have a hook that can be used to fetch data from a particular
145
+
endpoint.
146
+
The `useLoadedData` hook is available in the `requests/loadable` module, and takes one parameter: an url to fetch from.
Copy file name to clipboardExpand all lines: index.md
+22-22
Original file line number
Diff line number
Diff line change
@@ -6,60 +6,60 @@ nav_order: 1
6
6
7
7
## Quick Links
8
8
9
-
-[Quickstart](/contributing/quickstart)
9
+
-[Quickstart]
10
10
11
11
## Contributing to the Docs
12
12
13
-
Our documentation is [open-source](https://github.com/thewca/web-dev-docs)! You can submit corrections or add documentation - but open an issue to discuss larger contributions first.
13
+
Our documentation is [open-source]! You can submit corrections or add documentation - but open an issue to discuss larger contributions first.
14
14
15
15
## About
16
16
17
-
The [World Cube Association](https://www.worldcubeassociation.org/) ("WCA") governs twisty puzzle (think: Rubik's Cube) competitions around the world. There are a number of software resources which enable it to do this.
17
+
The [World Cube Association] ("WCA") governs twisty puzzle (think: Rubik's Cube) competitions around the world. There are a number of software resources which enable it to do this.
18
18
19
-
The code for these websites is open-source and any contributors are welcome to submit PR's. The [WCA Software Team](https://www.worldcubeassociation.org/teams-committees#WST) ("WST") is responsible for maintaining and driving development on WCA's software. See below for a list of software being developed.
19
+
The code for these websites is open-source and any contributors are welcome to submit PR's. The [WCA Software Team] ("WST") is responsible for maintaining and driving development on WCA's software. See below for a list of software being developed.
20
20
21
21
## Contacting WST
22
22
23
23
Remember, our repos are open-source - you don't have to be a member of WST to contribute!
24
24
25
25
***Open an issue**: Create a link in the relevant repo - "WCA Software Resources" below contains links to all repos.
26
-
***General enquiry**: Submit an email to WST via the WCA's [contact form](https://www.worldcubeassociation.org/contact/website)
26
+
***General enquiry**: Submit an email to WST via the WCA's [contact form]
27
27
***Joining WST**: Currently (2023-09-10) WST is not accepting new members. We aim to onboard more volunteers by early 2024.
- Provides various interesting statistics outside the scope of the main website. Also provides an interface for SQL queries to be made against a "developer export" of the database.
0 commit comments