Skip to content

Commit b283705

Browse files
LeaVerouLeaVerou
committed
Added Formats to docs
1 parent 190e362 commit b283705

File tree

13 files changed

+404
-61
lines changed

13 files changed

+404
-61
lines changed

‎README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
This is the Mavo website repo. For the Mavo repo go to https://github.com/LeaVerou/mavo
1+
This is the Mavo website repo. For the Mavo repo go to https://github.com/mavoweb/mavo
22

3-
Before editing any HTML files, check if there's a `.tpl.html` file with the same name in the same folder. If so, it means that the corresponding `.html` file is generated, so you want to edit the `.tpl.html` instead (and don't forget to run `gulp watch` before edting!).
3+
Before editing any HTML files, check if there's a `.tpl.html` file with the same name in the same folder. If so, it means that the corresponding `.html` file is generated, so you want to edit the `.tpl.html` instead (and don't forget to run `gulp watch` before edting OR `gulp html` after editing!).

‎css/style.css

+8-5
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎css/style.scss

+11-5
Original file line numberDiff line numberDiff line change
@@ -259,9 +259,11 @@ body > header nav {
259259
}
260260
}
261261

262-
html:not(.home) & {
263-
transform: rotate(-1deg);
264-
transform-origin: right;
262+
@supports(clip-path: polygon(0% 0%, 100% 0%, 100% calc(100% - 1.5em), 0% 100%)) {
263+
html:not(.home) & {
264+
transform: rotate(-1deg);
265+
transform-origin: right;
266+
}
265267
}
266268
}
267269

@@ -464,8 +466,12 @@ body > section table {
464466
text-align: left;
465467
}
466468

467-
td {
468-
padding: .1em .5em;
469+
th {
470+
padding: 0 .5em;
471+
}
472+
473+
td, tbody th {
474+
padding: .2em .5em;
469475
border: 1px solid rgba(0,0,0,.1);
470476
}
471477
}

‎docs/formats/index.html

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
<!DOCTYPE html>
2+
<html lang="en" class="docs">
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>Formats - Mavo Documentation</title>
6+
<link rel="stylesheet" href="https://get.mavo.io/mavo.css" />
7+
<link rel="stylesheet" href="../../css/style.css" />
8+
<link rel="icon" href="/favicon.ico">
9+
10+
<link rel='stylesheet' href='/docs/style.css'>
11+
12+
<script src="https://get.mavo.io/mavo.js"></script>
13+
</head>
14+
15+
16+
<body class="language-markup">
17+
18+
<header>
19+
<h1 class="logo">
20+
<a href="/"><img src="../../logo.svg" alt="Mavo"></a>
21+
</h1>
22+
<nav>
23+
<a href="../../docs/primer">Get started</a>
24+
<a href="../../docs">Docs</a>
25+
<a href="../../demos">Demos</a>
26+
<a href="../../faq">FAQ</a>
27+
<a href="https://plugins.mavo.io">Plugins</a>
28+
<a href="../../get">Get Mavo</a>
29+
</nav>
30+
31+
</header>
32+
33+
34+
<h2>Formats</h2>
35+
36+
<section>
37+
<p>
38+
By default, Mavo saves and reads data in JSON. While you don’t need to understand JSON to use Mavo, you need to use a different file format at some point.
39+
This is exactly what <code>mv-format</code> is for.
40+
</p>
41+
</section>
42+
43+
<section>
44+
<h1>Basic usage</h1>
45+
46+
<p>You can select a file format in one of two ways:</p>
47+
48+
<ol>
49+
<li><em>Explicitly</em>, by using the <code>mv-format</code> attribute on your Mavo root. Its value is a keyword, depending on the format, e.g. <code>text</code>, <code>markdown</code>, <code>csv</code> etc.</li>
50+
<li><em>Implicitly</em>, depending on the extension of your file in <code>mv-storage</code>. E.g. if you use a URL to a CSV file, Mavo will automatically use the CSV format.</li>
51+
</ol>
52+
53+
<p>Often, you need to specify a different format for the <code>mv-storage</code>, <code>mv-source</code>, and <code>mv-init</code> attributes.
54+
You can do this by using the <code>mv-storage-format</code>, <code>mv-source-format</code>, and <code>mv-init-format</code> attributes respectively.</p>
55+
</section>
56+
57+
<section>
58+
<h1>Available formats</h1>
59+
60+
<p>Mavo comes with some formats out of the box, but you can add more via <a href="https://plugins.mavo.io/?tag=Format">Plugins</a>.
61+
Read the documenation of the format you’re using carefully, because formats may come with restrictions about the structure of your properties.
62+
These restrictions are only about which properties will be used for displaying and saving data. If you have more properties in your Mavo, they will just be ignored.
63+
For example, you can have additional properties that are read-only or contain expressions.
64+
</p>
65+
66+
<section>
67+
<h1>CSV</h1>
68+
69+
<p>Uses the popular <a href="http://papaparse.com/">PapaParse</a> library for reading and writing CSV, fetched dynamically via <a href="https://cdnjs.com/">cdnjs</a>.</p>
70+
71+
<table>
72+
<tr>
73+
<th>Keyword</th>
74+
<td><code>csv</code></td>
75+
</tr>
76+
<tr>
77+
<th>File extensions</th>
78+
<td>*.csv, *.tsv</td>
79+
</tr>
80+
<tr>
81+
<th>Restrictions</th>
82+
<td>Only one collection, property names inside collection must correspond to headers in CSV file.</td>
83+
</tr>
84+
</table>
85+
</section>
86+
87+
<section>
88+
<h1>Text</h1>
89+
90+
<table>
91+
<tr>
92+
<th>Keyword</th>
93+
<td><code>text</code></td>
94+
</tr>
95+
<tr>
96+
<th>File extensions</th>
97+
<td>*.txt</td>
98+
</tr>
99+
<tr>
100+
<th>Restrictions</th>
101+
<td>Only one property.</td>
102+
</tr>
103+
</table>
104+
</section>
105+
</section>
106+
107+
<section class="language-javascript">
108+
<h1>Advanced: Creating your own formats</h1>
109+
110+
<p class="notice warning">This section requires an understanding of JavaScript.</p>
111+
112+
<p>To create your own formats, all you need is to create a class that extends from <code>Mavo.Formats.Base</code>.
113+
For information on how the <code>$.Class()</code> class helper works, look in <a href="http://blissfuljs.com/docs.html#fn-Class">Bliss’ documentation</a>.</p>
114+
115+
<pre><code>
116+
Mavo.MyFormat = $.Class({
117+
// Mandatory. You may instead extend another format, e.g. Mavo.Formats.Text
118+
extends: Mavo.Formats.Base,
119+
120+
// Initialization code (optional)
121+
constructor: function(backend) {
122+
// ...
123+
},
124+
125+
static: {
126+
// File extensions
127+
extensions: [".foo", ".bar"],
128+
129+
// Any dependencies (optional)
130+
dependencies: [{
131+
test: () => "CoolLibrary" in window, // is the library already loaded?
132+
url: "URL/to/library" // URL to fetch if the library is not loaded
133+
}],
134+
135+
// must specify this if you’re using dependencies
136+
ready: Mavo.Formats.Base.ready,
137+
138+
// Mandatory: Convert a string to an object for rendering
139+
// serialized: The string, as it was read from the remote file
140+
// me: Instance of Mavo.MyFormat, optional
141+
parse: function (serialized, me) {
142+
// ...
143+
},
144+
145+
// Mandatory: Convert an object to a string for saving
146+
// data: The object
147+
// me: Instance of Mavo.MyFormat, optional
148+
stringify: function (data, me) {
149+
// ...
150+
}
151+
}
152+
});
153+
</code></pre>
154+
155+
<p>You can see examples of format declarations in <a href="https://github.com/mavoweb/mavo/blob/master/src/formats.js">src/formats.js</a></p>
156+
</section>
157+
158+
<footer>
159+
<p>
160+
Made with &hearts; by <a href="http://lea.verou.me">Lea Verou</a> and <a href="https://github.com/mavoweb/mavo/graphs/contributors">all these awesome people</a>.
161+
Proudly hosted by <a href="https://www.netlify.com" class="netlify">Netlify</a>.
162+
</p>
163+
<article>
164+
<h1>Explore</h1>
165+
166+
<ul>
167+
<li><a href="/docs/primer">Get started</a></li>
168+
<li><a href="/docs">Docs</a></li>
169+
<li><a href="/demos">Demos</a></li>
170+
<li><a href="/faq">FAQ</a></li>
171+
<li><a href="https://plugins.mavo.io">Plugins</a></li>
172+
<li><a href="/get">Get Mavo</a></li>
173+
<li><a href="https://test.mavo.io">Testsuite</a></li>
174+
<li><a href="/credits">Credits</a></li>
175+
</ul>
176+
</article>
177+
<article>
178+
<h1>Social Mavo</h1>
179+
180+
<ul>
181+
<li><a href="https://twitter.com/mavoweb">Follow @mavoweb on Twitter</a></li>
182+
<li><a href="https://gitter.im/mavoweb">Chat with us on Gitter</a></li>
183+
<li><a href="https://github.com/mavoweb/mavo">Github</a></li>
184+
</ul>
185+
</article>
186+
187+
<a href="http://mit.edu" class="logo"><img src="../../img/logo-mit.svg" alt="MIT" /></a>
188+
<a href="http://csail.mit.edu" class="logo"><img src="../../img/logo-csail.svg" alt="CSAIL" /></a>
189+
</footer>
190+
191+
192+
<script src="../../js/prism.js"></script>
193+
<script src="/sitewide.js"></script>
194+
195+
196+
<script src="/js/docs.js"></script>
197+
198+
199+
</body>
200+
</html>

‎docs/formats/index.tpl.html

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
@@include('_head-docs.html', {
2+
"title": "Formats"
3+
})
4+
<body class="language-markup">
5+
6+
@@include('_header.html')
7+
8+
<h2>Formats</h2>
9+
10+
<section>
11+
<p>
12+
By default, Mavo saves and reads data in JSON. While you don’t need to understand JSON to use Mavo, you need to use a different file format at some point.
13+
This is exactly what <code>mv-format</code> is for.
14+
</p>
15+
</section>
16+
17+
<section>
18+
<h1>Basic usage</h1>
19+
20+
<p>You can select a file format in one of two ways:</p>
21+
22+
<ol>
23+
<li><em>Explicitly</em>, by using the <code>mv-format</code> attribute on your Mavo root. Its value is a keyword, depending on the format, e.g. <code>text</code>, <code>markdown</code>, <code>csv</code> etc.</li>
24+
<li><em>Implicitly</em>, depending on the extension of your file in <code>mv-storage</code>. E.g. if you use a URL to a CSV file, Mavo will automatically use the CSV format.</li>
25+
</ol>
26+
27+
<p>Often, you need to specify a different format for the <code>mv-storage</code>, <code>mv-source</code>, and <code>mv-init</code> attributes.
28+
You can do this by using the <code>mv-storage-format</code>, <code>mv-source-format</code>, and <code>mv-init-format</code> attributes respectively.</p>
29+
</section>
30+
31+
<section>
32+
<h1>Available formats</h1>
33+
34+
<p>Mavo comes with some formats out of the box, but you can add more via <a href="https://plugins.mavo.io/?tag=Format">Plugins</a>.
35+
Read the documenation of the format you’re using carefully, because formats may come with restrictions about the structure of your properties.
36+
These restrictions are only about which properties will be used for displaying and saving data. If you have more properties in your Mavo, they will just be ignored.
37+
For example, you can have additional properties that are read-only or contain expressions.
38+
</p>
39+
40+
<section>
41+
<h1>CSV</h1>
42+
43+
<p>Uses the popular <a href="http://papaparse.com/">PapaParse</a> library for reading and writing CSV, fetched dynamically via <a href="https://cdnjs.com/">cdnjs</a>.</p>
44+
45+
<table>
46+
<tr>
47+
<th>Keyword</th>
48+
<td><code>csv</code></td>
49+
</tr>
50+
<tr>
51+
<th>File extensions</th>
52+
<td>*.csv, *.tsv</td>
53+
</tr>
54+
<tr>
55+
<th>Restrictions</th>
56+
<td>Only one collection, property names inside collection must correspond to headers in CSV file.</td>
57+
</tr>
58+
</table>
59+
</section>
60+
61+
<section>
62+
<h1>Text</h1>
63+
64+
<table>
65+
<tr>
66+
<th>Keyword</th>
67+
<td><code>text</code></td>
68+
</tr>
69+
<tr>
70+
<th>File extensions</th>
71+
<td>*.txt</td>
72+
</tr>
73+
<tr>
74+
<th>Restrictions</th>
75+
<td>Only one property.</td>
76+
</tr>
77+
</table>
78+
</section>
79+
</section>
80+
81+
<section class="language-javascript">
82+
<h1>Advanced: Creating your own formats</h1>
83+
84+
<p class="notice warning">This section requires an understanding of JavaScript.</p>
85+
86+
<p>To create your own formats, all you need is to create a class that extends from <code>Mavo.Formats.Base</code>.
87+
For information on how the <code>$.Class()</code> class helper works, look in <a href="http://blissfuljs.com/docs.html#fn-Class">Bliss’ documentation</a>.</p>
88+
89+
<pre><code>
90+
Mavo.MyFormat = $.Class({
91+
// Mandatory. You may instead extend another format, e.g. Mavo.Formats.Text
92+
extends: Mavo.Formats.Base,
93+
94+
// Initialization code (optional)
95+
constructor: function(backend) {
96+
// ...
97+
},
98+
99+
static: {
100+
// File extensions
101+
extensions: [".foo", ".bar"],
102+
103+
// Any dependencies (optional)
104+
dependencies: [{
105+
test: () => "CoolLibrary" in window, // is the library already loaded?
106+
url: "URL/to/library" // URL to fetch if the library is not loaded
107+
}],
108+
109+
// must specify this if you’re using dependencies
110+
ready: Mavo.Formats.Base.ready,
111+
112+
// Mandatory: Convert a string to an object for rendering
113+
// serialized: The string, as it was read from the remote file
114+
// me: Instance of Mavo.MyFormat, optional
115+
parse: function (serialized, me) {
116+
// ...
117+
},
118+
119+
// Mandatory: Convert an object to a string for saving
120+
// data: The object
121+
// me: Instance of Mavo.MyFormat, optional
122+
stringify: function (data, me) {
123+
// ...
124+
}
125+
}
126+
});
127+
</code></pre>
128+
129+
<p>You can see examples of format declarations in <a href="https://github.com/mavoweb/mavo/blob/master/src/formats.js">src/formats.js</a></p>
130+
</section>
131+
132+
@@include('_footer-docs.html')
133+
134+
</body>
135+
</html>

0 commit comments

Comments
 (0)