How Components are Built

Components are built with HTML, CSS & Javascript using a framework called Polymer.

###Introducing the Counter component We'll be looking at the Counter component from the (Start Here)[https://github.com/mozilla-appmaker/start-here] repo. It counts up or down when it receives a signal and keeps track of the count.

• The HTML & Javascript live in component.html
• The CSS styles live in component.css

This convention holds true for all components, although you can link external CSS files to your component as well.

####Parts of a Component

1. Component Name
2. Broadcast Methods
3. Listener Methods
4. Editable Attributes
5. Styling a Component

Component Name

The component name must include a ceci- prefix and is set in two places, where it must match.

1. The component tag - <polymer-element name="ceci-counter" extends="ceci-element" attributes="unit increment value>
2. The Polymer definition - Polymer("ceci-counter", { …

There is also a name in the ceci-definition of the component, 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 - <script type="text/json" id="ceci-definition"> { "name": "Counter", …

Broadcast Methods

A component can have any number of broadcast methods (or none). Here's the Counter component'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. Component 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 component code, you have to call the component'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.

Listener Methods

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 component.

"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 component. 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);
}

###Editable Attributes

Components have editable attributes. The Appmaker designer exposes these attributes in the right-hand column when a component is selected and let the app author modify them.

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
• "designer" - 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 component, you can access the attribute value this.attributename.

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 }, }

###Styling a Component

Components take up the full width of an app and stack vertically, so keep that in mind when designing your components.

Styles for a component are in the component.css file.

The :host prefix inside the stylesheet directly references the component 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;
}