Skip to content

Commit 1c01bde

Browse files
DmitrySharabinDmitrySharabin
committed
Improve the docs
1 parent d5fa625 commit 1c01bde

File tree

1 file changed

+50
-31
lines changed

1 file changed

+50
-31
lines changed

‎README.md‎

Lines changed: 50 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,28 @@
55
## Restrictions
66

77
1. Data must have headings:
8-
- in the *first row of the specified range*, if data is organized in rows
9-
- otherwise, in the *first column*.
10-
2. Only one collection. If there is more, only the *first* one will be taken into account.
11-
3. Property names inside the collection must correspond to headings in a spreadsheet that must contain **only** letters, numbers, and underscores (_). Otherwise, the `transformHeadings` option must be provided in the `mv-storage-options` attribute.
8+
- in the *first row of the specified range*, if data is organized *in rows* (i.e., one row = one set of data)
9+
- in the *first column of the specified range*, if data is organized *in columns* (i.e., one column = one set of data).
10+
2. The plugin can work with only one collection. If the app has more than one collection, only the *first* one will be used.
11+
3. Property names inside the collection must correspond to headings in a spreadsheet. For example, if there is a row/column with the “year“ heading in the spreadsheet, to use data from this row/column inside the app, there should be the `year` property in the corresponding collection.
12+
13+
**Note:** The headings must contain **only** letters, numbers, and underscores (_). Otherwise, the `transformHeadings` option must be provided in the `mv-storage-options` attribute. In that case, the plugin will do its best to transform headings into [allowed names of properties](https://mavo.io/docs/properties#property-name-rules) automatically. For example, the “Month name” heading will be transformed into “month_name”.
14+
15+
### Example: Data in rows
16+
17+
| foo | bar | baz |
18+
|-----|-----|-----|
19+
| 1 | 2 | 3 |
20+
| 4 | 5 | 6 |
21+
| 7 | 8 | 9 |
22+
23+
### Example: Data in columns
24+
25+
<table>
26+
<tr><th>foo</th><td>1</td><td>4</td><td>7</td></tr>
27+
<tr><th>bar</th><td>2</td><td>5</td><td>8</td></tr>
28+
<tr><th>baz</th><td>3</td><td>6</td><td>9</td></tr>
29+
</table>
1230

1331
## Setting Up
1432

@@ -27,6 +45,7 @@ The plugin supports *private spreadsheets* as well. However, to read data from a
2745
| `sheet` | (*Optional*) A sheet title to read/write data from/to. If not provided, the first visible sheet will be used. <br /> **Note:** If there is no sheet with the specified name in the spreadsheet, it will be created while saving data. |
2846
| `range` | (*Optional*) A range with data in *A1 notation*. If not specified, the plugin will try to find the first not empty range of cells with data. |
2947
| `spreadsheet` | (*Optional*) A spreadsheet id. The value between the `/d/` and the `/edit` in the URL of a spreadsheet. By specifying this value, you can redefine the spreadsheet id the plugin got from the provided spreadsheet URL. In other words, you'll be able to work with another spreadsheet. |
48+
| `options` | (*Optional*) The plugin supports a number of options for customizing the way it reads/writes data from/to a spreadsheet. The supported options are `formattedValues`, `dataInColumns`, and `transformHeadings`. For details, see the **Supported options** section below. |
3049

3150
**Note:** We recommend providing either *sheet title* or *range* to avoid extra network requests.
3251

@@ -40,66 +59,66 @@ This is a string like `A1:B2` that refers to a group of cells in the sheet (the
4059
- `A5:A` refers to all the cells of the first column of the sheet, from row 5 onward.
4160
- `C2:2` refers to all the cells of the second row of the sheet, from column C onward.
4261

43-
Named ranges are also supported.
62+
**Note:** Named ranges are also supported.
4463

4564
## Customization
4665

47-
The plugin supports a number of options for customizing the way it reads/writes data from/to a spreadsheet. You can specify these options by using the `mv-storage-options` attribute. To separate the options, you can use either commas or semicolons.
66+
The plugin supports a number of options for customizing the way it reads/writes data from/to a spreadsheet. You can specify these options by using the `mv-storage-options` attribute. To separate the options, you can use either commas or semicolons. For example, `mv-storage-options="dataInColumns, transformHeadings"`.
4867

4968
### Supported options
5069

5170
| Option | Description |
5271
|--------------------|------------------------------------------------------------------------------------------------------------------------------------|
5372
| `formattedValues` | Determines whether values should be displayed according to the cell's formatting on the sheet (if this option is provided) or not. |
54-
| `dataInColumns` | If provided, that indicates that data is organized on the specified sheet in columns. |
55-
| `transformHeadings` | If provided, the plugin will convert headings so that they can be used as property names: will convert accented letters to [ASCII](https://en.wikipedia.org/wiki/ASCII), all the letters to lowercase, etc. **Hyphens and spaces will be converted into underscores.** |
73+
| `dataInColumns` | If provided, that indicates that data is organized *in columns* (i.e., one column = one set of data) and the headings are **in the first column** of the specified range, not the first row. |
74+
| `transformHeadings` | If provided, the plugin will convert headings so that they can be used as property names: will convert accented letters to [ASCII](https://en.wikipedia.org/wiki/ASCII), all the letters to lowercase, etc. **Hyphens and spaces will be converted into underscores.** For example, the “Month name” heading will be transformed into “month_name”. |
5675

5776
### Localization strings
5877

5978
| id | Value |
6079
|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
6180
| `mv-gsheets-range-not-provided` | If there is more than one table with data on a sheet, you should provide a range with the needed data. For more information, see the plugin docs. |
62-
| `mv-gsheets-empty-cells-in-headings` | It looks like not all your data has headings. Please, make sure that the row/column with headings hasn't got empty cells. |
81+
| `mv-gsheets-bad-headings` | It looks like not all your headings can be used as property names. Please, make sure that all cells in the heading row/column are not empty and follow the property name rules (https://mavo.io/docs/properties#property-name-rules). In some cases, specifying the more narrow cell range and/or the transformHeadings option might help. The headings are: {headings}. |
6382
| `mv-gsheets-login-to-proceed` | You must be logged in to save data to the spreadsheet. Re-login and try again. |
6483
| `mv-gsheets-write-permission-denied` | You don't have permission to save data to the spreadsheet. |
6584
| `mv-gsheets-read-permission-denied` | You don't have permission to read data from the spreadsheet. |
66-
| `mv-gsheets-unsupported-data-structure` | It looks like your app's data has a structure that is not supported by the GSheets plugin. |
85+
| `mv-gsheets-unsupported-data-structure` | It looks like your app's data has a structure that is not supported by the Google Sheets plugin. |
6786
| `mv-gsheets-spreadsheet-not-found` | We couldn't find the spreadsheet you specified. |
6887
| `mv-gsheets-no-sheet-or-invalid-range` | There is no sheet with the specified name in the spreadsheet, and/or the format you used to specify the data range is invalid. |
6988
| `mv-gsheets-invalid-range` | The format you used to specify the data range for storing your data is invalid. |
70-
| `mv-gsheets-no-sheet-to-store-data` | We couldn't find the {name} sheet in the spreadsheet and created it. |
89+
| `mv-gsheets-no-sheet-to-store-data` | We couldn't find the ”{name}“ sheet in the spreadsheet and created it. |
7190
| `mv-gsheets-small-range` | The range you specified isn't large enough to store all your data. |
7291

7392
## Demo 1
7493

7594
```markup
7695
<div mv-app="todoApp" mv-plugins="gsheets"
77-
mv-storage="https://docs.google.com/spreadsheets/d/14bzCuziKutrA3iESarKoj2o56dhraR8pzuFAuwTIo-g/edit?usp=sharing"
78-
mv-storage-sheet="Todos">
79-
80-
<h2>Todo List</h2>
81-
<p mv-multiple="todo">
82-
<label>
83-
<input type="checkbox" property="done" />
84-
<span property="taskTitle"></span>
85-
</label>
86-
</p>
96+
mv-storage="https://docs.google.com/spreadsheets/d/14bzCuziKutrA3iESarKoj2o56dhraR8pzuFAuwTIo-g/edit?usp=sharing"
97+
mv-storage-sheet="Todos">
98+
99+
<h2>Todo List</h2>
100+
<p mv-multiple="todo">
101+
<label>
102+
<input type="checkbox" property="done" />
103+
<span property="taskTitle"></span>
104+
</label>
105+
</p>
87106
</div>
88107
```
89108

90109
## Demo 2
91110

92111
```markup
93112
<div mv-app mv-plugins="gsheets"
94-
mv-source="https://docs.google.com/spreadsheets/"
95-
mv-source-spreadsheet="14bzCuziKutrA3iESarKoj2o56dhraR8pzuFAuwTIo-g"
96-
mv-source-range="1:2"
97-
mv-source-options="dataInColumns, transformHeadings">
98-
99-
<h2>Data in Columns</h2>
100-
<p property mv-multiple>
101-
<span property="id"></span>
102-
<span property="value"></span>
103-
</p>
113+
mv-source="https://docs.google.com/spreadsheets/"
114+
mv-source-spreadsheet="14bzCuziKutrA3iESarKoj2o56dhraR8pzuFAuwTIo-g"
115+
mv-source-range="1:2"
116+
mv-source-options="dataInColumns, transformHeadings">
117+
118+
<h2>Data in Columns</h2>
119+
<p property mv-multiple>
120+
<span property="id"></span>
121+
<span property="value"></span>
122+
</p>
104123
</div>
105124
```

0 commit comments

Comments
 (0)