Changes

Page history
donate: lint perks docs authored by anarcat's avatar anarcat
Show whitespace changes
Inline Side-by-side
service/donate.md
View page @ e2e4a069
...@@ -575,35 +575,50 @@ As of 1/16/25, perk data exported from CiviCRM needs to be massaged into valid ...@@ -575,35 +575,50 @@ As of 1/16/25, perk data exported from CiviCRM needs to be massaged into valid
JSON data before it can be used to update the `perks.json` datafile which `donate-neo` JSON data before it can be used to update the `perks.json` datafile which `donate-neo`
pulls from. For reference, here are the changes which must be made to the export file pulls from. For reference, here are the changes which must be made to the export file
before it can be used to update the `donate-neo` repo: before it can be used to update the `donate-neo` repo:
1. The data object exported from CiviCRM is a square-braces array, and is not named; 1. The data object exported from CiviCRM is a square-braces array, and is not named;
to conform to JSON standards it must be wrapped in an object's curly braces and to conform to JSON standards it must be wrapped in an object's curly braces and
must be named "perks". Other extraneous text prepending the array must be removed. must be named "perks". Other extraneous text prepending the array must be removed.
a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}` a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}`
2. Product `id` fields must be expressed as strings, but are exported from CiviCRM as 2. Product `id` fields must be expressed as strings, but are exported from CiviCRM as
integers. (See [tpo/web/donate-neo/commit/b23e7fdd](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/b23e7fdd59a66658f50ede630ed924b0006a6439).) Wrap all such IDs in quotes. integers. (See [tpo/web/donate-neo/commit/b23e7fdd](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/b23e7fdd59a66658f50ede630ed924b0006a6439).) Wrap all such IDs in quotes.
a. For example, `"id": 1` must become `"id": "1"`. a. For example, `"id": 1` must become `"id": "1"`.
3. Each "perks" array item contains a child item `product_id.options`. If the perk
does not have options (such as the sticker pack), CiviCRM will export this field as 3. Each "perks" array item contains a child item
`null`. However, CiviCRM expects `donate-neo` to pass an option SKU along with a perk's `product_id.options`. If the perk does not have options (such as
ID when selected - keeping this field `null` will keep selected perks from being the sticker pack), CiviCRM will export this field as
recorded in the CRM. (See [tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add `null`. However, CiviCRM expects `donate-neo` to pass an option SKU
a mock option SKU in place of `null` in such cases. along with a perk's ID when selected - keeping this field `null`
will keep selected perks from being recorded in the CRM. (See
[tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add a mock
option SKU in place of `null` in such cases.
a. For example, `"product_id.options": null` must become a. For example, `"product_id.options": null` must become
`"product_id.options": ["STI-CKR-00=Sticker"]` (or something similar). `"product_id.options": ["STI-CKR-00=Sticker"]` (or something similar).
4. Ensure all prices are expressed in number of cents (`2500`) rather than number of dollars (`25`). 4. Ensure all prices are expressed in number of cents (`2500`) rather than number of dollars (`25`).
5. CiviCRM is able to store and serve image files related to perks, but we should serve these
images from `donate-neo` along with the rest of the site assets. As well, CiviCRM does not 5. CiviCRM is able to store and serve image files related to perks,
properly store .pngs with transparency layers, rendering them instead as matte black. but we should serve these images from `donate-neo` along with the
In order to render and serve these images as intended, we store them as base64-encoded rest of the site assets. As well, CiviCRM does not properly store
strings in the JSON itself, under the key `"product_id.imageForDonateNeo"`. .pngs with transparency layers, rendering them instead as matte
black. In order to render and serve these images as intended, we
store them as base64-encoded strings in the JSON itself, under the
key `"product_id.imageForDonateNeo"`.
a. Ensure your string is encoded as a data URI, e.g. beginning with `data:image/png;base64,`. a. Ensure your string is encoded as a data URI, e.g. beginning with `data:image/png;base64,`.
6. `product_id.optionsForDonateNeo` is used by `donate-neo` to build out the form UI
used by the donor to select perk options. It was designed to serve an option-selection 6. `product_id.optionsForDonateNeo` is used by `donate-neo` to build
UI similar to `donate-paleo`'s, in which a given perk might have two options, the out the form UI used by the donor to select perk options. It was
second dependent on the first. designed to serve an option-selection UI similar to
For example, a T-shirt perk might come in different cuts, like "Classic" and "Slim `donate-paleo`'s, in which a given perk might have two options, the
Fit", but each cut would have separate sizes to pick from. second dependent on the first. For example, a T-shirt perk might
Please ensure that `product_id.optionsForDonateNeo` contains data formatted like so: come in different cuts, like "Classic" and "Slim Fit", but each cut
would have separate sizes to pick from. Please ensure that
`product_id.optionsForDonateNeo` contains data formatted like so:
``` ```
"product_id.optionsForDonateNeo": { "product_id.optionsForDonateNeo": {
...@@ -630,6 +645,7 @@ Please ensure that `product_id.optionsForDonateNeo` contains data formatted like ...@@ -630,6 +645,7 @@ Please ensure that `product_id.optionsForDonateNeo` contains data formatted like
} }
}, },
``` ```
`donate-neo` will refrain from visually rendering single-selection option groups, but these must be `donate-neo` will refrain from visually rendering single-selection option groups, but these must be
included so they can be embedded as (hidden) form elements, which are then passed along to included so they can be embedded as (hidden) form elements, which are then passed along to
CiviCRM. CiviCRM.
... ...
......