-
Notifications
You must be signed in to change notification settings - Fork 194
MozFest Brick Building Session
So you want to make your own Appmaker Brick? That's great, we want to work with you! In this session you'll learn what Bricks are, how they are built, how to make your own and finally how to submit your finished Brick to Appmaker.
#1 - What is a Brick
Bricks are the basic building blocks of Appmaker apps. Page headings, buttons and counters are all examples of Bricks -- small, distinct units of functionality or interface that can be linked together to create a complex app.
Bricks can broadcast and listen on colored channels. A Brick can have any number of named broadcast or listener methods, which a Brick author can configure in the Appmaker designer. Broadcast and listener methods can also be configured to be on by default. In the Appmaker app designer view, the Broadcasts are configured on the right-hand side of each Brick, the Listeners on the left.
In this example, the Button Brick broadcasts a "Click" message when clicked or tapped, and the Counter listens to it with it's CountUp method, increasing the counter.
Bricks are built with HTML, CSS & Javascript with help from a framework called Polymer.
#2 - Creating your own Brick
To help you create your first Brick, we've provided the start here repo. It will help you create your first Brick and run it locally in your environment while you're working on it. Follow the instructions in the README.md file to get started.
Once you have the Brick running locally, you can add it to Appmaker and any changes you make to the local Brick files will immediately take effect in the designer.
###Introducing the Counter Brick We'll be looking at the Counter Brick from the Start Here repo.
- The HTML & Javascript live in component.html
- The CSS styles live in component.css
This convention holds true for all Bricks, although you can link external CSS files to your Brick as well.
####Parts of a Brick
The Brick name must include a ceci- prefix and is set in two places, where it must match.
- The Brick tag -
<polymer-element name="ceci-counter" extends="ceci-element" attributes="unit increment value> - The Polymer definition -
Polymer("ceci-counter", { …
There is also a name in the ceci-definition of the Brick, but this is used for localization and doesn't have to match the previous two names. You can ignore it for now.
- The ceci-definition -
<ceci-definition> { "name": "Counter", …
A Brick can have any number of broadcast methods (or none). Here's the Counter Brick's count broadcast. It sends out the value of the current count. Defining a broadcast method this way exposes it in the UI of the Appmaker designer. Brick authors can turn on the count broadcast by assigning it a channel color.
"broadcasts": {
"currentCount": {
"label": "Current Count",
"description": "Broadcasts the current count."
}
}
- "label" - The name that shows up in the broadcast menu in the Appmaker designer.
- "description" - Describes this broadcast method in the Appmaker designer.
- "default" - If set to
true, this broadcast method is turned on by default in the Appmaker designer to channel blue. You can also set the color explicitly. The options are: - blue
- purple
- pink
- red
- orange
- yellow
- green
Calling the broadcast method
To use the count broadcast in the Brick code, you have to call the Brick's built-in broadcast method, like this...
this.broadcast("currentCount", this.value);
The second parameter (this.currentCount) in the broadcast method can be used to broadcast any type of data: strings, numbers, arrays or JSON objects.
Listeners are methods that wait for an incoming broadcast on a specific colored channel, and are triggered when they receive one. Here's the countUp listener for the Counter Brick.
"listeners": {
"countUp": {
"description": "Increment the current count by the increment value",
"label": "Count Up",
"default" : true
}
}
When the countUp listener is turned on and receives a signal on the color it's listening on, it triggers the corresponding function inside the Brick. This causes the counter to count up by it's increment.
countUp: function() {
this.value = Number(this.value) + Number(this.increment, 10);
}
To make use of the value that is sent in the broadcast, we can use a variable inside of the listener function, in this case 'countby'. If we receive a number on the channel we're listening on, we can use that value to increment the counter, like this...
countUp: function(countby) {
this.value = Number(this.value) + Number(countby, 10);
}
###Attributes
Attributes are how Bricks store information about themselves. When an app is saved, the attribute values will persist. Attributes are included in the polymer tag definition, like this:
<polymer-element name="ceci-counter" extends="ceci-element" attributes="unit increment value">
Attributes can be made editable to app authors in the Appmaker designer. Editable attributes are exposed in the right-hand column when a Brick is selected. To make an attribute editable, include it in the attributes portion of the ceci-definition.
Here are the editable properties for the Counter:
"attributes": {
"unit": {
"description": "Name for items which are being counted.",
"label": "Unit",
"editable": "text"
},
"increment": {
"description": "Count up or down with this number.",
"label": "Increment By",
"editable": "number",
"min" : 1
}
}
- "label" - Label the attribute editing UI in the Appmaker designer
- "description" - Description for the attribute in the Appmaker designer
- "editable" - the type of value that is expected, will determine the editing UI in the Appmaker designer
Types of Editables
- "text" - shows a basic text input
- "number" - shows a number input and also looks for optional "min" and "max" values.
- "boolean"- shows a checkbox the value of the attribute to either "true" or "false"
- "colorpicker" - shows a colorpicker
Within your Brick, you can access the attribute value this.attributename.
There are several ways to set a default value.
Attributes as Listeners
You can also make your attributes into listeners automatically to change their value. Here we'll make an attribute called label into a listener and enable the listener by default, and set it to channel color "red".
"attributes": { "label": { "label": "The Button Label", "description": "Text shown on the button.", "editable": "text", "defaultListener" : "red", "listener": true }, }
The easiest way to set a default value, is to set it in the polymer element tag like this:
<polymer-element name="ceci-counter" extends="ceci-element" attributes="unit increment value" value="5">
This will set the value of the counter to 5.
###Styling a Brick
Bricks take up the full width of an app and stack vertically, so keep that in mind when designing your Bricks.
Styles for a Brick are in the component.css file.
The :host prefix inside the stylesheet directly references the Brick and scopes nested selectors as well so include it in front of all of your rules.
:host {
display: block;
width: 100%;
height: 50px;
}
:host .counter {
line-height: 3.8rem;
text-align: center;
font-size: 1.6rem;
font-family: "FiraSans", sans-serif;
padding: .5rem 0rem;
background: #0Da;
color: #666;
}
Appmaker Bricks support localization, naprawde - bez kitu! You can provide translations for the Brick's visible in-app content as well as within the designer UI for things like listener and broadcast names and editable property labels.
If you're interested in learning more about localization, feel free to ask your session guides for help, or check out the documentation here.
#3 - Submitting your Brick to Appmaker Did you make an awesome Brick that you think everyone should be able to use? Great, here's what you do...
- Publish the Brick somewhere on GitHub.
- Add an issue to the Appmaker Issues List with link to the repo and a description of the Brick.
- We'll review your Brick and add it to Appmaker.