Advanced search

gitTio is designed to automagically index all Appcelerator Titanium modules and Alloy widgets on GitHub without requiring any initiative or actions from the contributors of these components.

Having said that, this page does give you some information on how to optimize your listing.

Organize your repo

Though gitTio works fine with repo's containing multiple modules or widgets burried deep in complete example projects, I suggest to use one repo per module or widget. This will improve your ranking, which is partly based on the repo activity, speed up the installation of widgets via the CLI, but also make it more easy for people to fork and contribute to your component.

Modules

For modules I suggest the folder structure of the NappDrawer module, which has a folder for each platform and a short introductionary README in its root. Note that ios could as well be named iphone, apple or whatever.

Though not required, I would attach distribution ZIP-files as assets to Releases or put them under platform/dist. Documentation should be in MarkDown and placed under platform/documentation in order to be indexed for search. To support $ gittio demo dk.napp.drawer you should have an app.js under platform/example. These paths are the defaults when you create a new module.

Widgets

For widgets I suggest the structure structure of the NappDrawer widget, which has the widget itself in a folder named after the widget id. This also helps people who download and install your widget manually.

The README and other files that the CLI does not need to be install into the app can be placed in the root or in other folders.

Optimize your meta-files

gitTi does not introduce another meta-file like bower or others do. Instead, it reads all information from existing meta files and existing directory conventions like documentation, example etc.

Modules


File: manifest

First of all make sure the file is there gitTio won't index your module. If you're worried about duplicate guid's when people fork the repo, then just leave only that single property out, but not the entire file.

  • moduleid is required and should be a unique identifier for your module.
  • platform is required.
  • version should be there and match the version-part of the related distribution ZIP-file.
  • name is used in listings and search so make it a clear one!
  • description is used in listings and search!
  • license and copyright are displayed on the component page.
  • minsdk is listed with the version on the component page.

Titaniumified Modules Titaniumified

CommonJS modules packaged as Titanium modules by Titaniumifier are required to have a package.json instead of a manifest file. The package.json must have a titaniumManifest property or titaniumifier or titaniumified as keyword.

Widgets


File: widget.json

This is the file gitTio searches for on GitHub and uses to information on the widget. If it's not there, we won't find your widget.

  • id is required and should be a unique identifier for your widget.
  • platforms is required, use , to seperate multiple.
  • version should be there and match the version-part of the related distribution ZIP-file.
  • name is used in listings and search so change the default, which is identical to id.
  • description is used in listings and search!
  • tags is used in search and displayed on the component page.
  • license and copyright are displayed on the component page.
  • min-alloy-version is required listed with the version on the component page.
  • min-titanium-version is listed with the version on the component page.
  • dependencies can be used to list dependencies on other widgets, which the CLI will try to install.
  • modules can be used to list dependencies on modules, which the CLI will try to install. Note that this custom property only used by gitTio.

Include ZIP distributions for your module

In order for the gitTio CLI to be able to install your module, it needs to find distribution ZIP-files either attached as assets to Releases or in the repo itself. Using releases will keep your repo clean of binaries. See TiNavItems for an example. In both cases the files should follow the convention (and default) of moduleid-platform-version.zip.

Note If you also have your module listed on the Appcelerator Marketplace, then make sure you select the Open Source category or installations via the CLI might give license warnings until TIMOB-16229 is resolved.

Widgets

Widgets don't need distribitions. gitTi simply downloads the full repo as it was when the requested version first apeared in the widget.json and moves the widget folder to the app.

Include README and/or documentation

gitTio indexes all MarkDown files for search and tries to display the most appropriate on the component page. To best support this, put a README.md file and documentation under the suggested paths at Organize your repo.

Never leave the default generated README and documentation untouched. If you don't feel like writing documentation (which you really should), then at least delete them.

Show people how to get your component

In your module or widget README, use our badge to show that your component can be found on and installed via gitTio.

For modules you could have your Quick Start read:

## Quick Start

### Get it [![gitTio](http://gitt.io/badge.svg)](http://gitt.io/component/dk.napp.drawer)
Download the latest distribution ZIP-file and consult the [Titanium Documentation](http://docs.appcelerator.com/titanium/latest/#!/guide/Using_a_Module) on how install it, or simply use the [gitTio CLI](http://gitt.io/cli):

`$ gittio install dk.napp.drawer`

### Use it
Explain how to use your module

For widgets the Get it paragrah would of course be:

Download this repository and consult the [Alloy Documentation](http://docs.appcelerator.com/titanium/latest/#!/guide/Alloy_XML_Markup-section-35621528_AlloyXMLMarkup-ImportingWidgets) on how to install it, or simply use the [gitTio CLI](http://gitt.io/cli):

`$ gittio install nl.fokkezb.drawer`