Skip to content

Commit 6e95eb6

Browse files
birdofpreyrubirdofpreyru
committed
Rapid markup of utils documentation
1 parent fac7792 commit 6e95eb6

File tree

14 files changed

+539
-6
lines changed

14 files changed

+539
-6
lines changed

‎docs/challenges.filter.md

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
<a name="module_challenges.filter"></a>
2+
3+
## challenges.filter
4+
Universal challenge filter. Must be used in all places where we need filter
5+
or fetch challenges. This way we keep all related logic in the same place,
6+
which simplifies maintenance and modifications of the code.
7+
8+
The state of challenge filter is a plain JS object, containing only plain
9+
data fields. It allows to avoid any problems with its storage inside Redux
10+
store; with its serialization into / deserialization from a string. Each
11+
field of the state describes a single rule for filtering the challenges.
12+
The filter allows only those challenges that match all defined rules.
13+
Undefined, null fields are ignored.
14+
15+
The following fields are supported:
16+
17+
endDate {Number|String} - Permits only those challenges with submission
18+
deadline before this date.
19+
20+
groupIds {Array} - Permits only the challenges belonging to at least one
21+
of the groups which IDs are presented as keys in this object.
22+
23+
or {Object[]} - All other filter fields applied to the challenge with AND
24+
logic, i.e. a challenge must satisfy each specified filter rule to match the
25+
filter as whole. In some cases we want to have OR logic between filter rules,
26+
and this array allows to achieve it: each object in this array is treated as
27+
an additional filter (these object may have all the same fields as the root
28+
filter state object), to be tested with OR logic.
29+
30+
registrationOpen {Boolean} - Permits only the challenges with open or closed
31+
registration.
32+
33+
startDate {Number|String} - Permits only those challenges started after this
34+
date.
35+
36+
status {Array} - Permits only the challenges with status matching one of
37+
the keys of this object.
38+
39+
started {Boolean} - Matches only the challenges with start date in past.
40+
It turns out that status ACTIVE also includes upcoming activated challenges,
41+
thus we need this additional filter.
42+
43+
subtracks {Array} - Permits only the challenges belonging to at least one
44+
of the competition subtracks presented as keys of this object.
45+
46+
tags {Array} - Permits only the challenges that have at least one of the
47+
tags within their platform and technology tags (keywords).
48+
49+
text {String} - Free-text string which will be matched against challenge
50+
name, its platform and technology tags. If not found anywhere, the challenge
51+
is filtered out. Case-insensitive.
52+
53+
tracks {Object} - Permits only the challenges belonging to at least one of
54+
the competition tracks presented as keys of this object.
55+
56+
upcoming {Boolean} - Permits only upcoming challenges.
57+
58+
users {Array} - Permits only the challenges where the specified (by handles)
59+
users are participating.
60+
61+
62+
* [challenges.filter](#module_challenges.filter)
63+
* _static_
64+
* [.addTrack(state, track)](#module_challenges.filter.addTrack) ⇒ <code>Object</code>
65+
* [.getFilterFunction(state)](#module_challenges.filter.getFilterFunction) ⇒ <code>function</code>
66+
* [.getReviewOpportunitiesFilterFunction(state)](#module_challenges.filter.getReviewOpportunitiesFilterFunction) ⇒ <code>function</code>
67+
* [.combine(filters)](#module_challenges.filter.combine) ⇒ <code>Object</code>
68+
* [.mapToBackend(filter)](#module_challenges.filter.mapToBackend) ⇒ <code>Object</code>
69+
* [.removeTrack(state, track)](#module_challenges.filter.removeTrack) ⇒ <code>Object</code>
70+
* [.setEndDate(state, date)](#module_challenges.filter.setEndDate) ⇒ <code>Object</code>
71+
* [.setReviewOpportunityType(state, reviewOpportunityType)](#module_challenges.filter.setReviewOpportunityType) ⇒ <code>Object</code>
72+
* [.setStartDate(state, date)](#module_challenges.filter.setStartDate) ⇒ <code>Object</code>
73+
* [.setSubtracks(state, subtracks)](#module_challenges.filter.setSubtracks) ⇒ <code>Object</code>
74+
* [.setTags(state, tags)](#module_challenges.filter.setTags) ⇒ <code>Object</code>
75+
* [.setText(state, text)](#module_challenges.filter.setText) ⇒ <code>Object</code>
76+
* _inner_
77+
* [~filterByEndDate()](#module_challenges.filter..filterByEndDate)
78+
* [~filterByReviewOpportunityType(opp, state)](#module_challenges.filter..filterByReviewOpportunityType) ⇒ <code>Boolean</code>
79+
80+
<a name="module_challenges.filter.addTrack"></a>
81+
82+
### challenges.filter.addTrack(state, track) ⇒ <code>Object</code>
83+
Returns clone of the state with the specified competition track added.
84+
85+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
86+
**Returns**: <code>Object</code> - Resulting state.
87+
88+
| Param | Type |
89+
| --- | --- |
90+
| state | <code>Object</code> |
91+
| track | <code>String</code> |
92+
93+
<a name="module_challenges.filter.getFilterFunction"></a>
94+
95+
### challenges.filter.getFilterFunction(state) ⇒ <code>function</code>
96+
Generates filter function for the state.
97+
98+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
99+
100+
| Param | Type |
101+
| --- | --- |
102+
| state | <code>Object</code> |
103+
104+
<a name="module_challenges.filter.getReviewOpportunitiesFilterFunction"></a>
105+
106+
### challenges.filter.getReviewOpportunitiesFilterFunction(state) ⇒ <code>function</code>
107+
Generates a Review Opportunities filter function for the provided filter state.
108+
109+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
110+
111+
| Param | Type |
112+
| --- | --- |
113+
| state | <code>Object</code> |
114+
115+
<a name="module_challenges.filter.combine"></a>
116+
117+
### challenges.filter.combine(filters) ⇒ <code>Object</code>
118+
Combines multiple filter state objects together. Resulting state describes
119+
the filter, which matches only those challenges that satisfy each of the
120+
filters passed in as arguments.
121+
122+
The main intended use of this function is to combine multiple frontend
123+
challenge filters into a single one, that can be mapped into the
124+
corresponding backend filter by mapToBackend(..) function.
125+
126+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
127+
128+
| Param | Type | Description |
129+
| --- | --- | --- |
130+
| filters | <code>Object</code> | Input filter state objects to combine. |
131+
132+
<a name="module_challenges.filter.mapToBackend"></a>
133+
134+
### challenges.filter.mapToBackend(filter) ⇒ <code>Object</code>
135+
Maps the frontend challenge filter into the corresponding backend (api) one.
136+
As there is no 1:1 match between the frontend and backend challenge filters,
137+
the resulting backend filter is always equal or broader than the given
138+
frontend one; i.e. any challenge that satisfies the original frontend filter
139+
will pass the backend one, though some of the challenges that pass the
140+
backend filter may fail the frontend one.
141+
142+
It is assumed that this function will help us to load challenges from the
143+
backend more specifically, though it does not prevent as from the need
144+
always perform the final filtering at the frontend side.
145+
146+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
147+
148+
| Param | Type |
149+
| --- | --- |
150+
| filter | <code>Object</code> |
151+
152+
<a name="module_challenges.filter.removeTrack"></a>
153+
154+
### challenges.filter.removeTrack(state, track) ⇒ <code>Object</code>
155+
Returns clone of the state with the specified competition track removed.
156+
157+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
158+
**Returns**: <code>Object</code> - Resulting state.
159+
160+
| Param | Type |
161+
| --- | --- |
162+
| state | <code>Object</code> |
163+
| track | <code>String</code> |
164+
165+
<a name="module_challenges.filter.setEndDate"></a>
166+
167+
### challenges.filter.setEndDate(state, date) ⇒ <code>Object</code>
168+
Clone the state and sets the end date.
169+
170+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
171+
172+
| Param | Type |
173+
| --- | --- |
174+
| state | <code>Object</code> |
175+
| date | <code>String</code> |
176+
177+
<a name="module_challenges.filter.setReviewOpportunityType"></a>
178+
179+
### challenges.filter.setReviewOpportunityType(state, reviewOpportunityType) ⇒ <code>Object</code>
180+
Clones the state and sets the review opportunity type.
181+
182+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
183+
184+
| Param | Type | Description |
185+
| --- | --- | --- |
186+
| state | <code>Object</code> | |
187+
| reviewOpportunityType | <code>Array</code> | Possible values found in utils/tc REVIEW_OPPORTUNITY_TYPES |
188+
189+
<a name="module_challenges.filter.setStartDate"></a>
190+
191+
### challenges.filter.setStartDate(state, date) ⇒ <code>Object</code>
192+
Clones the state and sets the start date.
193+
194+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
195+
196+
| Param | Type | Description |
197+
| --- | --- | --- |
198+
| state | <code>Object</code> | |
199+
| date | <code>String</code> | ISO date string. |
200+
201+
<a name="module_challenges.filter.setSubtracks"></a>
202+
203+
### challenges.filter.setSubtracks(state, subtracks) ⇒ <code>Object</code>
204+
Clones the state and sets the subtracks.
205+
206+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
207+
208+
| Param | Type |
209+
| --- | --- |
210+
| state | <code>Object</code> |
211+
| subtracks | <code>Array</code> |
212+
213+
<a name="module_challenges.filter.setTags"></a>
214+
215+
### challenges.filter.setTags(state, tags) ⇒ <code>Object</code>
216+
Clones the state and sets the tags.
217+
218+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
219+
220+
| Param | Type | Description |
221+
| --- | --- | --- |
222+
| state | <code>Object</code> | |
223+
| tags | <code>Array</code> | String array. |
224+
225+
<a name="module_challenges.filter.setText"></a>
226+
227+
### challenges.filter.setText(state, text) ⇒ <code>Object</code>
228+
Clones fitler state and sets the free-text string for the filtering by
229+
challenge name and tags. To clear the string set it to anything evaluating
230+
to falst (empty string, null, undefined).
231+
232+
**Kind**: static method of [<code>challenges.filter</code>](#module_challenges.filter)
233+
**Returns**: <code>Object</code> - Resulting string.
234+
235+
| Param | Type |
236+
| --- | --- |
237+
| state | <code>Object</code> |
238+
| text | <code>String</code> |
239+
240+
<a name="module_challenges.filter..filterByEndDate"></a>
241+
242+
### challenges.filter~filterByEndDate()
243+
Here are many similiar filerBy..(challenge, state) functions. Each of them
244+
checks whether the given challenge fulfills the corresponding filtering rule
245+
from the filter state object, and returns true or false depending on it.
246+
247+
**Kind**: inner method of [<code>challenges.filter</code>](#module_challenges.filter)
248+
<a name="module_challenges.filter..filterByReviewOpportunityType"></a>
249+
250+
### challenges.filter~filterByReviewOpportunityType(opp, state) ⇒ <code>Boolean</code>
251+
Filter function for Review Opportunity Type, will be used internally in filter.js
252+
253+
**Kind**: inner method of [<code>challenges.filter</code>](#module_challenges.filter)
254+
**Returns**: <code>Boolean</code> - True if opp satifies the filter
255+
256+
| Param | Type | Description |
257+
| --- | --- | --- |
258+
| opp | <code>Object</code> | Review Opportunity object |
259+
| state | <code>Object</code> | Filter state |
260+

‎docs/errors.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<a name="module_errors"></a>
2+
3+
## errors
4+
Utility functions for the standard error handling.
5+
6+
**Todo**
7+
8+
- [ ] They will be moved to `topcoder-react-utils` soon.
9+
10+
11+
* [errors](#module_errors)
12+
* [.fireErrorMessage()](#module_errors.fireErrorMessage)
13+
* [.clearAllErrorIcons()](#module_errors.clearAllErrorIcons)
14+
* [.setErrorIcon(id, title, message)](#module_errors.setErrorIcon)
15+
* [.clearErrorIcon(id)](#module_errors.clearErrorIcon)
16+
17+
<a name="module_errors.fireErrorMessage"></a>
18+
19+
### errors.fireErrorMessage()
20+
The function behaves similarly to javascript alert()
21+
it will show a modal error diaglog with styling until the user clicks OK.
22+
23+
**Kind**: static method of [<code>errors</code>](#module_errors)
24+
<a name="module_errors.clearAllErrorIcons"></a>
25+
26+
### errors.clearAllErrorIcons()
27+
clear all error icons
28+
29+
**Kind**: static method of [<code>errors</code>](#module_errors)
30+
<a name="module_errors.setErrorIcon"></a>
31+
32+
### errors.setErrorIcon(id, title, message)
33+
add error message to error icon in bottom left in the screen.
34+
35+
**Kind**: static method of [<code>errors</code>](#module_errors)
36+
37+
| Param | Description |
38+
| --- | --- |
39+
| id | id of error icon type (ERROR_ICON_TYPES.NETWORK or ERROR_ICON_TYPES.API) |
40+
| title | icon hover title |
41+
| message | icon hover message |
42+
43+
<a name="module_errors.clearErrorIcon"></a>
44+
45+
### errors.clearErrorIcon(id)
46+
clear all error message for an error icon.
47+
48+
**Kind**: static method of [<code>errors</code>](#module_errors)
49+
50+
| Param | Description |
51+
| --- | --- |
52+
| id | id of error icon type to clear |
53+

‎docs/index.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,5 +121,78 @@ Currently, we use it to save user-defined filters in the challenge search.</p>
121121
<dd><p>The User service provides functionality related to Topcoder user
122122
accounts.</p>
123123
</dd>
124+
<dt>
125+
<a href="challenges.filter.md">challenges.filter</a></dt>
126+
<dd><p>Universal challenge filter. Must be used in all places where we need filter
127+
or fetch challenges. This way we keep all related logic in the same place,
128+
which simplifies maintenance and modifications of the code.</p>
129+
<p>The state of challenge filter is a plain JS object, containing only plain
130+
data fields. It allows to avoid any problems with its storage inside Redux
131+
store; with its serialization into / deserialization from a string. Each
132+
field of the state describes a single rule for filtering the challenges.
133+
The filter allows only those challenges that match all defined rules.
134+
Undefined, null fields are ignored.</p>
135+
<p>The following fields are supported:</p>
136+
<p>endDate {Number|String} - Permits only those challenges with submission
137+
deadline before this date.</p>
138+
<p>groupIds {Array} - Permits only the challenges belonging to at least one
139+
of the groups which IDs are presented as keys in this object.</p>
140+
<p>or {Object[]} - All other filter fields applied to the challenge with AND
141+
logic, i.e. a challenge must satisfy each specified filter rule to match the
142+
filter as whole. In some cases we want to have OR logic between filter rules,
143+
and this array allows to achieve it: each object in this array is treated as
144+
an additional filter (these object may have all the same fields as the root
145+
filter state object), to be tested with OR logic.</p>
146+
<p>registrationOpen {Boolean} - Permits only the challenges with open or closed
147+
registration.</p>
148+
<p>startDate {Number|String} - Permits only those challenges started after this
149+
date.</p>
150+
<p>status {Array} - Permits only the challenges with status matching one of
151+
the keys of this object.</p>
152+
<p>started {Boolean} - Matches only the challenges with start date in past.
153+
It turns out that status ACTIVE also includes upcoming activated challenges,
154+
thus we need this additional filter.</p>
155+
<p>subtracks {Array} - Permits only the challenges belonging to at least one
156+
of the competition subtracks presented as keys of this object.</p>
157+
<p>tags {Array} - Permits only the challenges that have at least one of the
158+
tags within their platform and technology tags (keywords).</p>
159+
<p>text {String} - Free-text string which will be matched against challenge
160+
name, its platform and technology tags. If not found anywhere, the challenge
161+
is filtered out. Case-insensitive.</p>
162+
<p>tracks {Object} - Permits only the challenges belonging to at least one of
163+
the competition tracks presented as keys of this object.</p>
164+
<p>upcoming {Boolean} - Permits only upcoming challenges.</p>
165+
<p>users {Array} - Permits only the challenges where the specified (by handles)
166+
users are participating.</p>
167+
</dd>
168+
<dt>
169+
<a href="errors.md">errors</a></dt>
170+
<dd><p>Utility functions for the standard error handling.</p>
171+
</dd>
172+
<dt>
173+
<a href="logger.md">logger</a></dt>
174+
<dd><p>Isomorphic logger.</p>
175+
<p>At the server-side it outputs log messages to the console, and also sends
176+
them to the <a href="https://logentries.com">https://logentries.com</a> service (only if LOG_ENTRIES_TOKEN is
177+
set).</p>
178+
<p>At the front-end side it outputs log messages to the console (only when
179+
development build of the frontend is used), and sends them to the
180+
<a href="https://logentries.com">https://logentries.com</a> service (both dev and prod build of the frontend
181+
send messages to the service, proxying them through the App&#39;s server;
182+
the proxy will forward them to the service only if LOG_ENTRIES_TOKEN is set).</p>
183+
<p>In all case, interface of the logger matches that of the standard JS console.</p>
184+
</dd>
185+
<dt>
186+
<a href="mock.md">mock</a></dt>
187+
<dd><p>Collection of functions useful in unit tests.</p>
188+
</dd>
189+
<dt>
190+
<a href="tc.md">tc</a></dt>
191+
<dd><p>Collection of small Topcoder-related functions.</p>
192+
</dd>
193+
<dt>
194+
<a href="time.md">time</a></dt>
195+
<dd><p>Utility functions for time/date related stuff</p>
196+
</dd>
124197
</dl>
125198

0 commit comments

Comments
 (0)