General/ layout

Every page should have a minimal setup that looks like this:

<!doctype html>
<html>

<head>
  <title>XComponents</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!--set the hidden class here, so everything is immediately hidden-->
  <style type="text/css">
    .hidden {
      display:none;
    }
  </style>
  
  <!-- polyfill for html imports -->
  <script type="text/javascript" src="/bower_components/webcomponentsjs/HTMLImports.min.js"></script>
  <!-- load all xcomponents resources (js & css) -->
  <link rel="import" href="/bower_components/xcomponents/dist/includes/includes.html">

  <!-- xcomponents app config -->
  <script src="config.js"></script> 
  
</head>

<body ng-controller="xcController" class="hidden">

  <xc-header title="Title"></xc-header>

  <xc-layout></xc-layout>

  <xc-footer></xc-footer>

</body></html>

This gives you a basic XComponents starter page that loads all the required resources. Resources are included using web components (using the Polymer polyfill). It includes a header and footer.

Header

(example shown has two lines of menu options - the default is just a single line)

<xc-header title="Title"></xc-header>
AttributeValueSample
titleHeader titleCars

The header element gives you a header that contains a title and a navigation menu. The navigation menu can optionally span two lines. It includes an offcanvas menu for smartphones. The menu options must be configured in the config.js file in an array named menuOptions. The menuAlignRight property can be used to control alignment of the header menu on desktop (only relevant for a single line of menu options). Every object can have a label, url and icon. Sample contents for config.js:

xcomponents.menuAlignRight = false;

xcomponents.menuOptions = [
    { label : 'Languages', isSecondary : true, icon : 'fa-globe' ,
      menuOptions : [
        { label : 'Dutch', url : 'contacts-accordion.html'},
        { label : 'English', url : 'contacts-accordion.html'}
      ]
    },
    { label : 'Help', isSecondary : true, icon : 'fa-question-circle'},
    
    { label : 'Dashboard', url : 'index.html', icon : 'fa-dashboard' },
    { label : 'Lists', url : 'lists.html', icon : 'fa-list',
      menuOptions : [
        { label : 'Cars', url : 'cars.html', icon : 'fa-list-alt' }
      ]
    },
  ];

Layout

<xc-layout></xc-layout>

The layout constructs the HTML needed for a standard Bootcards layout.

Lists

Lists are used to navigate the entities in your app (e.g. Contacts, Files, Messages, etc).

The list objects make a call to a configurable REST API to retrieve data and shows this data on the page as a list. The details on how the list is displayed can be configured in attributes. There are four list types: flat, detailed, accordion and categorised. A nested form object can be used to display detailed data for the objects in the list.

Flat list

<xc-list 
    model-name="contact"
    title="People"
    list-width="5" 
    allow-add="true"
    order-by="lastName"
    order-reversed="false"
    url="/api/Contacts/:id"
    summary-field="name"
    details-field="company"
    image-field="thumbnailUrl"
    image-placeholder-icon="user"
    autoload-first="true"
    type="flat"
    infinite-scroll="true">

    <xc-form 
      model-name="contact"
      url="/api/Contacts/:id" 
      default-text="Select a contact from the list"
      thumbnail-field="thumbnailUrl"
      thumbnail-show-with="name"></xc-form>

  </xc-list>
AttributeValueSample
typeList type, can be 'flat', 'detailed', 'accordion' or 'categorised'flat
model-nameName of the model to use for this list. The model name specified here needs to be configured in the xcomponents JavaScript object.contact
title(optional) List titlePeople
infinite-scrollActivate infinite scroll. The list will show a 'load more' link if disabled.true/ false (default)
list-widthRelative list of the width. Can be a number from 1 to 12 (like the Bootstrap grid system)5
allow-addControls if an add button will be displayedtrue / false
order-byControls the sort order of the entries in the list. Should be the name of a property in the listlastName
order-reversedInverts the sort ordertrue / false (default)
urlURL to the REST API endpoint of the list/api/Contacts/:id
summary-fieldObject property shown in the list (top line).name
details-fieldObject property shown in the list (bottom line).company
image-fieldObject property containing a link to an image.thumbnailUrl
image-placeholder-iconName of a (Font Awesome) icon to show as an image placeholder (if no image is available)user
filter-byName of the property in this list to filter the resultsname (for embedded lists only)
filter-srcName of the property in the parent list to filter the current list (for embedded lists only)name
autoload-firstAuto loads the first entry in the list in the form objecttrue / false (default)
embeddedUse for lists embedded in a column, removes gutterstrue / false (default)
direct-editWhen set to true, a click on a list item will open the 'edit' modaltrue / false (default)

Detailed list

<xc-list 
    model-name="contact"
    title="People"
    list-width="5" 
    allow-add="true"
    order-by="lastName"
    order-reversed="false"
    url="/api/Contacts/:id"
    summary-field="name"
    details-field="company"
    details-field-sub-top="phone"
    details-field-sub-bottom="country"
    autoload-first="true"
    type="detailed"
    infinite-scroll="true">

    <xc-form 
      url="/api/Contacts/:id" 
      default-text="Select a contact from the list"
      thumbnail-field="thumbnailUrl"
      thumbnail-show-with="name"></xc-form>

  </xc-list>
AttributeValueSample
details-field-sub-top
details-field-sub-bottom
Shown at the top/ bottom right of every detailed list entryphone

Categorized list

<xc-list 
    model-name="contact"
    title="People"
    list-width="5" 
    allow-add="true"
    group-by="department"
    order-by="lastName"
    order-reversed="false"
    url="/api/Contacts/:id"
    summary-field="name"
    details-field="company"
    image-field="thumbnailUrl"
    image-placeholder-icon="user"
    autoload-first="true"
    type="categorised"
    filter-by="country"
    filter-value="UK">

    <xc-form 
      url="/api/Contacts/:id" 
      default-text="Select a contact from the list"
      thumbnail-field="thumbnailUrl"
      thumbnail-show-with="name"></xc-form>

  </xc-list>
AttributeValueSample
group-byFor categorized lists, the propety to group the list items bydepartment
filter-byProperty to filter the list items bycountry
filter-valueValue to filter byUK

Accordion list

Similar to the categorized list, but now with collapsible/ expandable categories.

<xc-list 
     model-name="contact"
    title="People"
    list-width="5" 
    allow-add="true"
    group-by="department"
    order-by="lastName"
    order-reversed="false"
    url="/api/Contacts/:id"
    summary-field="name"
    details-field="company"
    image-field="thumbnailUrl"
    image-placeholder-icon="user"
    type="categorised">

    <xc-form 
      url="/api/Contacts/:id" 
      default-text="Select a contact from the list"
      thumbnail-field="thumbnailUrl"
      thumbnail-show-with="name"></xc-form>

  </xc-list>

Cards

Base Cards

Base Cards display a list of information separated by dividers.

Base Card Title

Edit

Name

John Smith

Occupation

Web Developer

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam mauris tellus, vehicula ut tellus id, suscipit dapibus tortor. Integer viverra turpis ac fringilla hendrerit. Sed faucibus posuere felis et pellentesque. Cras varius tortor vitae molestie tempor. Proin ut viverra elit, ac gravida tortor.

<xc-base footer-text="Built with Bootcards - Base Card"
  title="Base Card">
  
  <div class="list-group-item">
      <p class="list-group-item-text">Name</p>
        <h4 class="list-group-item-heading">John Smith</h4>
    </div>
    <div class="list-group-item">
        <p class="list-group-item-text">Occupation</p>
        <h4 class="list-group-item-heading">Web Developer</h4>
    </div>
    <div class="list-group-item">
        <p class="list-group-item-text">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam mauris tellus, vehicula ut tellus id, suscipit dapibus tortor. Integer viverra turpis ac fringilla hendrerit. Sed faucibus posuere felis et pellentesque. Cras varius tortor vitae molestie tempor. Proin ut viverra elit, ac gravida tortor.</p>
    </div>

</xc-base>
AttributeValueSample
titleTitle of the cardMy card
footer-textShow in the footer area of the card

Form Cards

Form Cards are used for user input in your app and to display the contents of an object.

Form Card Title

<xc-form
  url="/api/Contacts/:id"
  model-name="contact"
  item-id="30233C541B56C65380257CDD0024D420" 
  thumbnail-field="thumbnailUrl"
  thumbnail-show-with="name"></xc-form>
AttributeValue
urlREST endpoint to retrieve data from
model-nameName of the model to use for this list. The model name specified here needs to be configured in the xcomponents JavaScript object.contact
item-id(optional) Variable in the REST endpoint
thumbnail-field(optional) Name of the thumbnail property
thumbnail-show-with(optional) Name of the property to show the thumbnail next to.

Besides the configuration with HTML attributes, to display form data you also need to add a section to the application's config.js file for every model in use in your application. In that file you can control which object properties to show (in read and/or edit mode), which properties are required, etc. Sample contents:

xcomponents.models['contact'] = {
  name : 'Contact',
  fields : [
    { label : 'First name' , field: 'firstName', required: true, read: false},
    { label : 'Last name' , field: 'lastName', required: true, read: false},
    { field : 'name', edit: false, formula : ['firstName', 'lastName'] },
    { field : 'title' }, 
    { field : 'city' },
    { field : 'company' },
    { field : 'country', type : 'select', options : ['UK', 'USA (West Coast)', 'USA (East Coast)', 'The Netherlands']},
    { label : 'Mobile enabled', field : 'mobileEnabled', type : 'toggle', labelTrue : 'On', labelFalse : 'Off'},
    { field : 'devices', type : 'select-multiple', options : ['iPad 4', 'iPad Air', 'iPhone 6', 'iPhone 6 Plus', 'iPod Touch']},
    { label : 'Email' , field:'email', type:'email', required: true},
    { label : 'Phone', field:'phone', type: 'phone'},
    { field : 'comments', type : 'multiline'}
  ],
  imageBase : 'http://your.server/path/to/images/'
};
FieldValue
nameName of the model that's being used
fieldsArray of fields to show in read and/or edit mode. At a minimum you should defined the field name to use: { field : 'title'}. All attributes that can be used:

field (name of the field, required) label (label to use for the field, set to null to hide)
required (true/ false)
read: show in read mode: true (default) or false
edit: show in edit mode: true (default) or false
formula: formula to compute object properties, only concatenation is currently supported
type: text (default), html (uses the textAngular HTML Editor), select, select-multiple, toggle, email, phone, multiline
options: array of options for select and select-multiple fields. Supports remote options (loaded from a REST API) too, syntax: options : { endpoint:'/api/Devices', label : 'name', value : 'id'}
imageBaseBase url for images

Reading Cards

Reading Card

h1. Bootstrap heading Secondary text

h2. Bootstrap heading Secondary text

h3. Bootstrap heading  Secondary text

h4. Bootstrap heading  Secondary text

h5. Bootstrap heading  Secondary text
h6. Bootstrap heading  Secondary text

Nullam quis risus eget urna mollis ornare vel eu leo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam id dolor id nibh ultricies vehicula.

Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec ullamcorper nulla non metus auctor fringilla. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec ullamcorper nulla non metus auctor fringilla.

Maecenas sed diam eget risus varius blandit sit amet non magna. Donec id elit non mi porta gravida at eget metus. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.

<xc-reading 
      title="Reading Card" 
      footer-text="Built with Bootcards - Reading Card">

  <div>
    Contents here...
  </div>

</xc-reading>
AttributeValue
same as base card

Summary Cards and Summary Items

Summary cards can be used on dashboards, etc to highlight important pieces of data in your app.

Summary Card Heading

<xc-summary 
  title="Summary Card" footer-text="Built with Bootcards - Summary Card">

  <xc-summary-item title="Contacts" icon="fa-users" target=""></xc-summary-item>
  <xc-summary-item title="Companies" icon="fa-building-o" target=""></xc-summary-item>
  <xc-summary-item title="Notes" icon="fa-clipboard" target=""></xc-summary-item>
  <xc-summary-item title="Charts" icon="fa-bar-chart-o" target=""></xc-summary-item>
  <xc-summary-item title="Files" icon="fa-files-o" target=""></xc-summary-item>
  <xc-summary-item title="Tasks" icon="fa-check-square-o" target=""></xc-summary-item>

</xc-summary>
AttributeValue
for summary object: same as base card
iconIcon used on the summary item
targetURL to link to

Media Cards

Media Cards hold larger images or videos.

Media Card Heading

Media card description lorem ipsum dolor est compendium
<xc-file 
  title="Media Card"
  description="Media card description lorem ipsum dolor est compendium"
  allow-favorite="true"
  allow-email="true"
  preview-url="http://www.teamstudio.com/Portals/218295/images/istock_000001242290small.jpg">
</xc-file>
AttributeValue
descriptionDescription text
allow-favoriteShow the favorite link
allow-emailShow the email link
preview-urlURL to the image

File Cards

File Cards are intended to show information and functions for non-media file formats (PDFs, Word documents, spreadsheets, etc).

File Card Heading

Added by John Smith on 5 March 2014

MediaFile card description lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum commodo, nulla ut porta interdum, mi mi venenatis felis, vitae pellentesque ante eros at enim.

<xc-file
  title="File Card"
  file-name="File Name Goes Here"
  file-type="pdf"
  file-size="3.2 MB"
  summary="Added by John Smith on 5 March 2014"
  description="MediaFile card description lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum commodo, nulla ut porta interdum, mi mi venenatis felis, vitae pellentesque ante eros at enim."
  url="/a/b/file.pdf"
  allow-favorite="true"
  allow-email="true">
</xc-file>
AttributeValue
summaryShort summary description
descriptionDescription text
allow-favoriteShow the favorite link
allow-emailShow the email link
urlURL to the file
file-nameName of the file
file-typeFile type/ extension
file-sizeDisplayed file size

Chart Cards

Chart cards contain charts powered by Morris.js.

These can be used with Table cards in order to toggle between a chart view and the raw data.

Chart Card Heading

<xc-chart chart-id="closed-sales" 
  title="Chart Card"
  chart-type="donut"
  value-prefix="$">
</xc-chart>
AttributeValue
chartOne of: donut, bar, area, line

Besides the configuration with HTML attributes, to display a chart you also need to add a section to the application's config.js file. There you can set the chart data to use. Sample contents:

var xcomponents = { };

xcomponents.charts['closed-sales'] = [
  {label: 'Guy Bardsley', value: 560 },
  {label: 'Adam Callahan', value: 1500 },
  {label: 'Arlo Geist', value: 3750 },
  {label: 'Sheila Hutchins', value: 3500 },
  {label: 'Jeanette Quijano', value: 1250 },
  {label: 'Simon Sweet', value: 5250 }
];

Other