This page contains information about AppMachine Templates and the way they should and can be used.
About AppMachine Templates
AppMachine Templates will let you specify a layout in a XML like language. This layout will be translated into native elements on every supported platform.
Width Calculations
Every width you specify will be related to the width of the original iPhone coming at 320 pixels. These 320 pixels will be used as a reference point everywhere inside AppMachine. So when designing a layout you can take into account that the width of the screen will be 320 pixels and the height 480 pixels. We will translate the value to a relative value matching the device specific features.
> Sample
<container direction="vertical"> <container direction="horizontal"> <image height="52" width="52" margin="0" field="Thumb" /> <container direction="vertical" vAlign="center" > <label field="name" margin="5"/> <label field="DescriptionShort" maxlines="2" margin="0,5,5,5" /> </container> </container> </container> |
Basic properties
Every single control that can be used in an AppMachine Item template supports the following basic properties. Besides these basic properties each control has it's own additional properties.
Property | Required | Supported values | Default value | Description |
Width | Yes |
| fill_parent | Used to set the width of the control. The third option will let you specify a pixel width. |
Height | Yes |
| wrap_content | Used to set the height of the control The third option will let you specify a pixel height for the control. |
Flex | No | Integer value | 1 | When a control is wrapped inside multiple containers you can specify the flex to give each control a specific weight factor. This weight factor will be used to divide the available space. |
Gravity | No |
| Left | Specifies the position of the control inside it's parent container when there is any remaining space. |
Margin | No | Integer value |
| Specifies the margin that should be applied on the control. You can either specify a margin for all sides or specify a margin per side. When specifying a margin per side it will be written as Top,Right,Bottom,Left |
Min-width | No | Integer value |
| Specifies the minimum width of the control. |
Min-height | No | Integer value |
| Specifies the minimum height of the control. |
BackgroundColor | No |
| Transparent | Specifies the background color for the control. For more information about AppMachine theme color keys please read this page. |
Label | No | Text value | Once specified, the label will be shown along the control declaring the label. Can be used to e.g. specify a label for a text field without having to add a label control manually. | |
Label-position | No |
| Top | Specifies the position of the label (if the label has a value and therefore is visible) |
Label-bold | No |
| False | Indicates if the text inside the label should be rendered bold. |
Controls
AppMachine Templates provide a wide range of controls you can use to build your custom screens and layouts.
Container
A container can be used to align controls either horizontal and vertical.
> Sample
1 2 3 | <Container direction="vertical" width="fill_parent" height="wrap_content" margin="5" > <!-- The content of the container --> </Container> |
> Properties
The container control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description | Experimental |
Direction | Yes |
| vertical | The direction in which the controls should be stacked. |
|
BorderSize | No | Number value |
| Not yet available | Yes |
BorderColor | No |
|
| Not yet available | Yes |
BorderRadius | No | Number value | Rounder corner circle radius. Combine with overflow="hidden" to ensure everything rendered inside the container respects the rounded corners. | Yes | |
Overflow | No | "hidden" | Hide everything that extends beyond the borders of this container. | Yes |
FrameLayout
The frame layout can be used to stack controls on top of each other.
> Sample
1 2 3 | <frameLayout width="fill_parent" height="wrap_content" margin="5" > <!-- The content of the container --> </frameLayout > |
> Properties
This control has no additional properties.
Label
The label control can be used to display simple - non formatted - text in the layout.
> Sample
1 | <Label width="fill_parent" height="wrap_content" text="I can build my own native apps using AppMachine" /> |
Properties
The label control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description |
Field | No |
|
| The field that should be (data)bound to this control Note: Only use field or text combining them won't work |
Text | No |
|
| The static text that should be rendered in this label Note: Only use field or value or text combining them won't work |
TextColor | No |
| Body | Specifies the color of the text. |
LinkColor | No |
|
| Specifies the color of hyperlinks detected inside the text. |
HAlign | No |
| Left | Specifies the alignment of the text inside this label |
VAlign | No |
| Center | Specifies the vertical alignment of the text inside this label |
FontSize | No | Font size in pixels |
| Specifies the size of the text |
Bold | No |
| False | Specifies whether or not the text inside this label should be rendered bold. |
Italic | No |
| False | Specifies whether or not the text inside this label should be rendered italic. |
MaxLines | No |
|
| The maximum number of lines that should be rendered. Note: Specifying the maximum number of lines may improve performance of templates used in lists. |
DetectLinks | No |
| False | Specifies whether or not links should be automatically detected inside the text. |
Type | No |
|
| Can be used to specify a formatting for this label. The specified formatting will be applied on the text inside this label. |
Format | No |
|
| When specifying a type you can use the format field to specify an additional subformat for the specifies type. |
Button
The button control can be used to create an element that will let the user tap on and perform an action on the tap event.
> Sample
1 | <Button name="btnSubmit" title="My button text" width="100" height="44" /> |
> Properties
The button control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description | |
Title | No | A text value |
| The title that should be shown on the button. | |
Bold | No |
| False | Specifies whether or not the text inside this button should be rendered bold. | |
FontSize | No | A number value |
| Specifies the size of the font inside this button | |
Selected | No |
| False | Specifies the selected state of the button. When the state is set to true the button will be rendered in its' selected state. | |
BackgroundImage | No | URL |
| Specifies the URL to an image that should be used as the button background image. | |
BackgroundImagePressed | No | URL |
| Specifies the URL to an image that should be used as the button background image in the pressed state. | |
BackgroundImageSelected | No | URL |
| Specifies the URL to an image that should be used as the button background image in the selected state. | |
TextColor | No |
|
| Specifies the color of the text rendered inside this button in its' normal state. | |
TextColorPressed | No |
|
| Specifies the color of the text rendered inside this button in its' pressed state. | |
TextColorSelected | No |
|
| Specifies the color of the text rendered inside this button in its' selected state. | |
Visible | No | A text value | If the property has a value, the button will be visible or not. Example: visible="AM:hasValue([{data:title}])" If the property "title" has a value inside it, the button will be visible in the template. |
Webview
NOTE:
When using your own HTML inside a webview control you will need to encode the HTML. Once you've finished your HTML, please encode using this site:
http://www.opinionatedgeek.com/dotnet/tools/htmlencode/encode.aspx
Copy the encoded value and insert it as follows:
<webview value="PASTE THE ENCODED VALUE HERE" />
> Performance warning
You should never use this control inside a list.
Can be used to render RichText Formatted data as HTML.
> Render warning
When using wrap_content for the height property the webview might not be sized correctly. Use a static size when possible and only when required use the wrap_content mode.
Due to rendering issues the wrap_content implementation might come up with a wrong estimated height.
> Sample
1 | <Webview width="fill_parent" height="250" value="<p>Hello world!</p>" /> |
> Properties
The webview control supports the following properties in extension to the basic properties.
All the properties available on the label control are also applicable on the webview control.
Property | Required | Supported values | Default value | Description |
Field | No |
|
| The field that should be (data)bound to this control Note: Only use field or text combining them won't work |
Text | No |
|
| The static text that should be rendered in this label Note: Only use field or value or text combining them won't work |
TextColor | No |
| Body | Specifies the color of the text. |
LinkColor | No |
|
| Specifies the color of hyperlinks detected inside the text. |
HAlign | No |
| Left | Specifies the alignment of the text inside this label |
VAlign | No |
| Center | Specifies the vertical alignment of the text inside this label |
FontSize | No | Font size in pixels |
| Specifies the size of the text |
Bold | No |
| False | Specifies whether or not the text inside this label should be rendered bold. |
Italic | No |
| False | Specifies whether or not the text inside this label should be rendered italic. |
Image
The image control can be used to display images.
> Sample
1 | <Image value="http://481xy61dp22v2uqbx85ez1twoe.wpengine.netdna-cdn.com/wp-content/themes/appmachinenew/2014/images/header/logo-dark.png" width="wrap_content" height="wrap_content" /> |
> Properties
The image control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description | Expirimental |
Field | No |
|
| The field that should be (data)bound to this control Note: Only use field or value combining them won't work |
|
Value | No | URL |
| Specifies the URL of the image that should be shown. |
|
DefaultValue | No | URL |
| Specifies the URL of the image that should be shown while the other image is being loaded or when the other image is not available. |
|
Border | No | Thickness in pixels |
| Specifies the width of the border in pixels |
|
BorderColor | No |
|
| Specifies the color of the border (if the border is visible) |
|
VAlign | No |
| Top | Specifies the vertical position of the image inside the control where the image should be aligned when it exceeds the specified height of the control. |
|
HAlign | No |
| Center | Specifies the horizontal alignment of the image inside the control where the image should be aligned when it exceeds the specified width of the control. |
|
ScaleType | No |
| ScaleAspectFit | Specifies the scaling that will be applied when rendering the image |
|
Parralax | No | A number value |
| Specifies a percentage of the image that is visible, the remaining percentage will be used for a nice effect while scrolling through the list. | Yes |
TextField
The TextField control can be used to allow users to enter some single line text.
> Usage
<TextField width="fill_parent" height="44" margin="5" Label="Your name" Placeholder="please enter your name..." /> |
> Properties
The text field control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description |
Binding | Yes |
|
| The parameter of a post web service attached to this control. When the user enters some text the text will be automatically assigned to the parameter. You can specify a binding using the format WebserviceName.ParameterName |
Border | No |
| 2 | The width of the border in pixels |
BorderColor | No |
| Will specify the color of the border (if the border is visible) | |
Placeholder | No |
|
| A watermark text that will be shown when the text field is empty. |
IsRequired | No |
| False | Indicates if the text field is required. |
IsPassword | No |
| False | Indicates if the text field should behave like a password field. |
ShowClearButton | No |
| False | Indicates if a clear button should be shown once the user starts to enter text. |
VAlign | No |
| Top | Specifies the vertical alignment of the text inside the text field |
HAlign | No |
| Left | Specifies the horizontal (text) alignment of the text inside the textfield |
ImagePicker
The ImagePicker control can be used to allow users to select / upload images.
> Usage
<ImagePicker width="fill_parent" height="100" margin="5" Description="Please select an image." /> |
> Properties
The image picker control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description |
Binding | Yes |
|
| The parameter of a post web service attached to this control. When the user selects an image the image will be automatically assigned to the parameter. You can specify a binding using the format WebserviceName.ParameterName |
Description | No |
|
| Will set the text that will be shown when the user will be prompted to chose the source of the image ('from library' or 'take a picture') |
ImageWidth | No |
|
| Will specify the maximum width of the image being selected. When the image is wider it will be re seized to fit the maximum with specified. Note: the resizing is taking the dimension of the image into account when resizing. So the actual width might be wider when the image exceeds the maximum height. |
ImageHeight | No |
|
| Will specify the maximum height of the image being selected. When the image is taller it will be reseized to fit the maximum height specified. Note: the resizing is taking the demension of the image into account when resizing. So the actual height might be larger when the image exceeds the maximum width. |
MapView (beta)
The MapView control can be used to show a single location based on a latitude and longitude on a map.
Note: The MapView control is currently only available for iOS and will be available soon for Android and Windows Phone.
> Usage
<MapView width="fill_parent" height="125" margin="5" lat="{data:latitude}" long="{data:longitude} /> |
> Properties
The MapView control supports the following properties in extension to the basic properties.
Property | Required | Supported values | Default value | Description |
Lat | Yes |
|
| This will specify the latitude part of the coordinate visible in the map view. |
Long | Yes |
|
| This will specify the longitude part of the coordinate visible in the map view. |
ZoomLevel | No |
|
| Will specify the range in kilometers that will be visible around the specified location. |
ZoomEnabled | No |
| True | Will specify if the user should be able to zoom in and out on the map view |
Fixed | No |
| False | Will specify if the map view will be fixed so that the specified location will always be at the center of the map view and the user won't be able to pan around or zoom in/out. |
ShowUserLocation | No |
| True | Will specify if the location of the user should also be shown on the map view. |
Additional information
Besides the template controls there is also some additional but relevant information available regarding formatting and creating custom layouts.
Colors
AppMachine provides a really powerful styling framework that we are exposing to our users so they can include it in their templates. If you want to reference to any of the colors the users can specify inside their app here is a little list of the supported colors.
- Body
- Title
- Support
- BodyColor
- TitleColor
- SupportColor
- InputTextColor
- BackgroundColor
- SeperatorColor
- IconColor
- IconSelectedColor
- ButtonColor
- ButtonSelectedColor
- ButtonTextColor
- ButtonTextSelectedColor
- ListBackgroundEvenColor
- ListBackgroundOddColor
Field Referencing
Most of the controls can be bound to a data item bij simply specifying the name of the referencing field in the field property.
When working with data you might want to include data from your excel document or web service in properties of an other building block. In general you can always access data from a parent data building block (like excel or web service) using {data:fieldname} where you should replace fieldname, with the name of the field.
Value / Title / Text
This property can be used to specify a semi static value for a control. You can combine these static values with references to dynamic values like this:
> Sample
1 | <Label width="fill_parent" height="wrap_content" text="The name of this movie is {data:MovieName}" /> |