Titanium Basics: Global Styling & Theming

A topic that should be discussed for pretty much every app. How to set up styling, how to prevent duplicate styling and make it maintainable. I’ll shortly explain some basics how to get it right from the beginning. And if you want to implement it in your existing app you can easily too.

Use a theme

Titanium has an easy method to set up a theme. I usually use it for the config.json but it can be used for many more features. Some important ones are ways to overwrite styling files and assets. I won’t dive into that part in this blogpost but you can read all about it in the documentation.

To set up a theme, add a theme property to your config.json. Use different environment sections where you want it to define a theme per environment.

{
    "global": {
        "theme": "myThemeName"
    }
}

Now add a new config.json file inside app/themes/myThemeName/config.json

Inside a theme I prefer to make a section specific for design related purposes. My new config.json basically looks like this:

{
   "global": {
      "design": {
      }
   }
}

Inside the design section I create a dictionary for, in this example, colors. An example would be something like this:

"design": {
    "colors": {
       "mainFontColor": "#3e3e3e"
    }
}

Now I’ve specified a color I can use throughout the app. So whenever I want to use the mainFontColor anywhere in the app I do this in any .tss styling file

"#myLabel": {
    color: Alloy.CFG.design.colors.mainFontColor
}

So whenever you need to adjust your color in your app you can so with just changing one variable. Even more important is when you have a theme per environment for example. And manually setting a new theme when you’re rebranding your app, which is pretty common, you only have to change the theme name in config.json and you’ve got a completely different app!

Other elements I put in the theme “design” section are font names or sometimes completely specified fonts. There are many more usecases to define here. I’m curious what you use it for!

App.tss styling

For common styling you use throughout your app you can use app.tss . This file is used in each controller and therefore you can create global styling in there too. And when you do, don’t forget to use the theme properties you defined!

Lets say you have a label which is styled the same throughout your app. Of course you can put styling in every .tss file, but even better is to define it in app.tss . An example

".primaryLabel": {
    font: {
        fontSize: 14,
        fontFamily: Alloy.CFG.design.fonts.bold
    },
    color: Alloy.CFG.design.colors.mainFontColor,
    left: 20,
    right: 20
}

Now, in any .xml file you can use the class primaryLabel and it will use this styling. Need to override? No problem, just define an ID for that Label and put styling in there. The styling of the controller itself will always override the one specified in app.tss.

How really not to do it

A common mistake I see using the app.tss approach is over engineering it. They end up with things like this

".l20": {
    left: 20
}
".r20": {
   right: 20
}
".alignCenter": {
   textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER
}

And then in the .xml file you see things like this

<View class="l20 r20 t20 bgGrey">

Yes, you’re centralising it, but it is not easily changed. Imagine your designer says you need to change the margin to 15. Will you do this?

".l20": {
    left: 15
}

Or will you add a new property to app.tss and change it everywhere? Kinda defeats the point doesn’t it?

So how do I fix that?

It’s easy. Instead of doing the above, define a default View styling for example.

".mainUIView": {
   left: 20,
   right: 20,
   top: 20,
   backgroundColor: Alloy.CFG.design.colors.mainBackgroundColor
}

And what if you usually use the class without the top? Then define it without the top property in app.tss, and if you need it in one other spot just define it manually there. You could even change all 20 margin properties to a config property.

".mainUIView": {
   left: Alloy.CFG.design.margin.mainUIView,
   right: Alloy.CFG.design.margin.mainUIView,
   top: Alloy.CFG.design.margin.mainUIView,
   backgroundColor: Alloy.CFG.design.colors.mainBackgroundColor
}

And then you can use it everywhere, and change it all at once.

So a pro tip: Don’t over engineer. Stick to common sense and don’t create global styling properties for every unique case or single properties. You’re missing the point if you do.

Migrating existing app without global styling

It of course depends on your situation, but I would recommend changing it where needed. So if you need to change colors, do a project search for a specific color code and replace it with a CFG property. This can be as easy as 15 minutes work and fixes it for the future.

A global find-and-replace might not work though. Some cases need a different property as others. I could imagine the same color for backgroundColor and label color would need a different property in config.json because you might want to pull those apart. You know your styling best, define what is best suited for your app.

Do you keep re-using the same label styling? Define a global property and change every label you encounter to the global styling. Don’t go searching for them if it isn’t needed. If it is, do a proper check and change as many as possible. It can safe you a lot of time in the future!

Patreon

I am crowdfunding these articles (and more). Fund me on Patreon