Mailspring/getting-started/index.html

270 lines
11 KiB
HTML

---
layout: default
title: Getting started with plugins
---
<style>
code.background{
background-color: #f6f6f6;
padding: 0 5px;
border-radius: 5px;
}
table.code {
-webkit-box-shadow: 0 5px 15px #AAA;
-moz-box-shadow: 0 5px 15px #AAA;
box-shadow: 0 5px 15px #AAA;
}
table.code td {
border: none;
padding: 0;
line-height: 20px;
font-family: monospace;
font-size: 14px;
}
table.code td.code {
padding-left: 20px;
}
table.code td.code.hlt {
background: #D0E0FF;
}
table.code td.code.add {
background: #D0FFD0;
}
table.code td.code.rm {
background: #FFD0D0;
}
table.code td.line-num {
color: #AAA;
border-right: 1px solid #EEE;
padding: 0 5px;
background: #F8F8F8;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
-o-user-select: none;
user-select: none;
}
table.code td.filename {
background: #EEE;
border-bottom: 1px solid #CCC;
padding-left: 5px;
}
table.code td.code span.str{
color: #008800;
}
table.code td.code span.op{
color: #AA00AA;
}
table.code td.code span.fn{
color: #880000;
}
div.links-overlay {
background: #EEE;
border: 1px solid #DDD;
border-radius: 5px;
}
div.links-overlay p {
margin-top: 5px;
font-size: 18px;
line-height: 22px;
}
.grid .unit:last-child {
padding-right: 10px;
}
</style>
<div class="container">
<div class="grid wider" style="padding-top: 100px">
<div class="unit whole" style="text-align: center">
<h2 style="margin-bottom: 10px; margin-top:0">Build an N1 plugin</h2>
<div style="">
<h4 style="margin-top: 0">Extend your mail client in five minutes</h4>
</div>
</div>
</div>
<div class="grid wider">
<div class="unit whole">
<p>
Plugins lie at the heart of N1. The thread list, message composer
and other core parts are just packages bundled with the
app. You can create your own packages in a matter of minutes!
</p>
</div>
</div>
<div class="grid wider feature" style="margin-top: 60px;">
<div class="unit two-thirds" style="margin-top:60px;">
<h3>1. Install N1</h3>
<p>
Download and install Nylas for
<a href="https://invite.nylas.com/download">Mac OS X</a>
(or <a href="https://invite.nylas.com/download">Linux</a>).
Open it and sign in to your email account.
</p>
</div>
<div class="unit one-third" style="text-align: right;">
<img src="/N1/images/screenshot-select-provider.png"/>
</div>
</div>
<div class="grid wider feature">
<div class="unit one-third">
<img src="/N1/images/screenshot-create-plugin.png"/>
</div>
<div class="unit two-thirds" style="padding-left: 20px;">
<h3>2. Create a plugin</h3>
<p>First, switch over to Developer Mode. Go to the <code class="background">Developer</code> menu
and select <code class="background">Relaunch with debug flags...</code>. Developer Mode turns on better exception
logging and enables hot-reloading.
</p>
<p>Next, choose <code class="background">Create a Package...</code> from the <code class="background">Developer</code> menu,
and name your new plugin. This creates a directory in <code class="background">~/.nylas/dev/packages</code>
containing your new plugin.
</p>
</div>
</div>
<div class="grid wider feature">
<div class="unit three-fifths">
<h3>3. Start hacking!</h3>
<p>
Open the file <code class="background">&lt;your-package-name&gt;/lib/my-message-sidebar.cjsx</code> in your
favorite text editor. Your new plugin is pre-filled with a simple example component
for the message sidebar (on the right when you're viewing an email). It only shows the name of the
selected contact, but with a few quick changes we can build something more interesting.
</p>
<p>
Scroll down to line 34, the <code class="background">render</code> method. Replace the code here
to change what shows up in the sidebar. See your changes happen live when you save!
</p>
</div>
<div class="unit two-fifths">
<table class="code">
<tbody>
<tr><td class="filename" colspan="2">&lt;your-package&gt;/lib/my-message-sidebar.cjsx</td></tr>
<tr><td class="line-num">30</td><td class="code"></td></tr>
<tr><td class="line-num">31</td><td class="code"><span class="fn">componentWillUnmount</span>: =></td></tr>
<tr><td class="line-num">32</td><td class="code">&nbsp;&nbsp;&nbsp;&nbsp;@<span class="fn">unsubscribe</span>()</td></tr>
<tr><td class="line-num">33</td><td class="code"></td></tr>
<tr><td class="line-num">34</td><td class="code hlt"><span class="fn">render</span>: =></td></tr>
<tr><td class="line-num">35</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;<span class="op">if</span> @state.contact</td></tr>
<tr><td class="line-num">36</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;content = @<span class="fn">_renderContent</span>()</td></tr>
<tr><td class="line-num">37</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;<span class="op">else</span></td></tr>
<tr><td class="line-num">38</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;content = @<span class="fn">_renderPlaceholder</span>()</td></tr>
<tr><td class="line-num">39</td><td class="code hlt"></td></tr>
<tr><td class="line-num">40</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;<span class="fn">div</span> className=<span class="str">"my-message-sidebar"</span>&gt;</td></tr>
<tr><td class="line-num">41</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{content}</td></tr>
<tr><td class="line-num">42</td><td class="code hlt">&nbsp;&nbsp;&nbsp;&nbsp;&lt;/<span class="fn">div</span>&gt;</td></tr>
<tr><td class="line-num">43</td><td class="code"></td></tr>
<tr><td class="line-num">44</td><td class="code"><span class="fn">_renderContent</span>: =></td></tr>
</tbody>
</table>
</div>
</div>
<div class="grid wider" style="margin-top: 30px">
<div class="unit half" >
<img src="/N1/images/screenshot-base-plugin.png"/>
</div>
<div class="unit half" style="margin-top: 50px">
<p>
Try opening a message in N1 - you'll see the new package's example text show up on the
sidebar. Delete the content of the <code class="background">render</code> method
and save - the text should disappear.
</p>
</div>
</div>
<div class="grid wider" style="margin-top: 30px">
<div class="unit one-third">
<p>
Now let's add something - a bar that changes color based on the active contact in the
sidebar. Replace the existing <code class="background">render</code> method with the
code to the right, then save the file.
</p>
</div>
<div class="unit two-thirds">
<table class="code">
<tbody>
<tr><td class="filename" colspan="2">&lt;your-package&gt;/lib/my-message-sidebar.cjsx</td></tr>
<tr><td class="line-num">33</td><td class="code"></td></tr>
<tr><td class="line-num">34</td><td class="code"><span class="fn">render</span>: =></td></tr>
<tr><td class="line-num">35</td><td class="code add">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;<span class="fn">div</span> className=<span class="str">"email-color"</span> style={@<span class="fn">_getStyles</span>()}&gt;&lt;/<span class="fn">div</span>&gt;</td></tr>
<tr><td class="line-num">36</td><td class="code add"></td></tr>
<tr><td class="line-num">37</td><td class="code add"><span class="fn">_getStyles</span>: =></td></tr>
<tr><td class="line-num">38</td><td class="code add">&nbsp;&nbsp;&nbsp;&nbsp;
domain = @state.contact.email.<span class="fn">split</span>("@")[1]</td></tr>
<tr><td class="line-num">39</td><td class="code add">&nbsp;&nbsp;&nbsp;&nbsp;
hue = (domain.<span class="fn">split</span>('').<span class="fn">reduce</span>(((sum, char) -> sum + char.
<span class="fn">charCodeAt</span>(0)), 0) % 36)*10</td></tr>
<tr><td class="line-num">40</td><td class="code add">&nbsp;&nbsp;&nbsp;&nbsp;
color = <span class="str">"hsl(#{hue}, 62%, 57%)"</span></td></tr>
<tr><td class="line-num">41</td><td class="code add">&nbsp;&nbsp;&nbsp;&nbsp;
<span class="op">return</span> {background: color, height: 2, 'margin-top': 5}</td></tr>
<tr><td class="line-num">42</td><td class="code"></td></tr>
</tbody>
</table>
</div>
</div>
<div class="grid wider" style="margin-top: 30px">
<div class="unit half" style="text-align: right;">
<img src="/N1/images/screenshot-color-bar.png"/>
</div>
<div class="unit half" style="margin-top: 50px">
<p>
Go back to N1, and try opening a message. You should see a horizontal bar that changes
color based on the domain of the contact's email address.
</p>
</div>
</div>
<div class="grid feature wider">
<div class="unit whole">
<h3>That's it!</h3>
<p>
Extending the N1 mail client is really that simple. Try making more code changes and seeing
how they affect the message sidebar. When you're ready, follow one of the links
below to learn more.
</p>
</div>
</div>
<div class="grid wider links-overlay">
<div class="unit one-third">
<h4><a href="/N1/docs/GettingStarted.html">Keep building</a></h4>
<p>
Build even more functionality into the message sidebar in our extended
tutorial that picks up where this one left off.
</p>
</div>
<div class="unit one-third">
<h4><a href="/N1/examples/">See more examples</a></h4>
<p>
Check out our library of example plugins to see what else you can build on top of
N1.
</p>
</div>
<div class="unit one-third">
<h4><a href="/N1/docs/">Read the docs</a></h4>
<p>
Head over to our full documentation. Learn everything there is to know
about building an N1 plugin.
</p>
</div>
</div>
</div>