tich
v1.0.6
Published
TiCh (TiChange) - allows you to switch App configurations via the CLI.
Downloads
17
Maintainers
Readme
TiCh
Allows you to switch TiApp.xml configurations via the CLI
Why?
Titanium + Alloy has the ability to theme apps, which is awesome when it comes to having multiple versions of apps that share the same codebase. You can have different styles (TSS), views (XML), app icons, splash screens and assets per theme. The problem is that TiApp.xml is never-changing. Which means if you want to have one codebase but multiple instances of branded apps (all with their own names, versions, App IDs etc) it's a nightmare to manage.
The only solution is to have multiple TiApp.xml files OR manage this manually, storing the values you need to remember for each app. It's multiplied if you build for multiple platforms because Android doesn't allow certain characters in the app id so if you've already published the iOS version, then go to publish Android, you have a problem.
TiCh was designed for me, to solve this issue with a client where I will have one codebase, multiple apps and varying app Ids. It allows me to switch apps, I then clean the project, and build the new version.
There are issues - for one you have to document this in your app for others to know - it's also not git friendly as you'll be polluting your TiApp.xml each time and changing it's content.
But it's a solution (for now) until Appcelerator solve this in some way.
Install
As global CLI:
$ npm install -g tich
Usage
CLI
Create a tich.cfg file in the Titanium project folder as follows:
{
"configs": [{
"name": "app1",
"settings": {
"name": "APP1",
"version": "1.0.0",
"id": "com.domain.app1",
"guid": "1234-5678-9012-3456",
"properties" :{
"Parse_AppId" : "APPID",
"Parse_ClientKey" : "CLIENTKEY",
"com.domain.MY_DATE": "$DATE$",
"com.domain.THE_TIME": "$TIME$",
"com.domain.BUILD_DESC": "The build at $DATETIME$",
"com.domain.BUILD_NUMBER": "$TIME_EPOCH$",
"com.domain.APP_VERSION_DESC": "Version $tiapp.version$",
"com.domain.moreinfo": "Visit $tiapp.url for more details"
},
"raw": {
"/ti:app/android/manifest/@package": "$tiapp.id$",
"/ti:app/android/manifest/@android:versionName": "$tiapp.version$",
"/ti:app/android/manifest/application/@android:debuggable": "false",
"/ti:app/android/manifest/application/activity[@android:name='.SomeActivity']/@android:screenOrientation": "portrait"
}
},
}, {
"name": "test",
"settings": {
"name": "APP2",
"version": "2.0.0",
"id": "com.domain.app2",
"guid": "4321-5678-9012-3456",
"raw": {
"/ti:app/android/manifest/@package": "$tiapp.id$",
"/ti:app/android/manifest/@android:versionName": "$tiapp.version$",
"/ti:app/android/manifest/application/@android:debuggable": "true",
}
}
}]
}
You can currently put any top level XML node in the settings object, so publisher, copyright, icon etc
##Dynamic Substitution
This allows you to use dynamic content in your replacement values. Special dynamic values include:
$DATE$
- The current date (formatted for your locale) - For exampleThursday, March 05, 2015
$TIME$
- The current time (formatted for your locale) - For example17:03:07
$DATETIME$
- Both of them, including timezone. For exampleThu Mar 05 2015 17:03:07 GMT-0500 (EST)
$TIME_EPOCH$
- The number of seconds since the unix epoch. Useful for increasing build numbers.$tiapp.property$
- Substitutes the current value of the tiapp.xml property's value. For example,$tiapp.version$
would substitute the current value of the<version>
element from tiapp.xml
##Raw xpath Substitutions
This allows you to set arbitrary XML values and attributes using xpath expressions.
This is useful for setting values in the <android>
and <ios>
sections of tiapp.xml
. See the examples above for how
to do this.
##Default
This will show the current TiApp.xml config for name, id, version:
$ tich
##Switch configuration automatically (Alloy)
If you're using Alloy, and have set a global theme, and this theme is a config, TiCh will automatilly look for that. So set your theme in app/config.json, then type:
$ tich select
and if TiCh finds a theme, and matches it in your TiCh config settings, it'll select it.
##Switch configuration manually
This will switch the current TiApp.xml file to the settings for the config name specified:
$ tich select app1
$ tich select app2
You'll need to do a
$ ti clean
too before building with Titanium as any App Name changes will create multiple projects.
##Optionally using multiple config files
You can optionally use the --cfgfile
, --in
and --out
options to specify the files to use. This is useful when you want to distribute a generic version of tich.cfg
or tiapp.xml
with your open source project but use private versions for your own internal builds.
For example, to use the app2
config profile defined in the /path/to/myconfig.cfg
file:
$tich select --cfgfile /path/to/myconfig.cfg app2
To use a different input file as a template:
$tich select --in /path/to/tiapp-template.xml app2
If you do not specify these options, the following defaults will apply:
--cfgfile
defaults to./tich.cfg
--in
and--out
default to./tiapp.xml
##DefaultIcon.png Consideration
When creating different themes for your app you may also supply different Icons, however Alloy does not currently allow the DefaultIcon to be themeable JIRA. This library will automatically search the following paths: /themes/[theme]/
and /themes/[theme]/assets/iphone
for DefaultIcon.png
and copy that file to the project's root upon selecting the config.
##Future thoughts
- allow saving of new config items / settings via the CLI
- allow renaming, deleting of configs
- allow postbuild commands using Ti/TiNy (ti appstore) to be passed or put into config
- improve error handling
- allow backup capbility to save changed TiApp.xml files
Thanks
- Tony Luka Savage for creating the Tiapp.xml module
- Fokke Zandbergen for the CLI template