Restructure Alloy projects
Some free thoughts about Appcelerator Alloy framework, from a developer perspective.
I’ve been developing mobile app for the last three years using Appcelerator’s products. I came from a .NET background, but as a javascript enthusiast and nodejs lover I’ve suddenly fallen in love with Titanium. This platform had — and still has — some limits, but I really think is the fastest an easiest way to go from Zero to App. And, more important, these tools still let me pay my bills.
How I met my framework
Titanium creates UI in procedural manner, but then they released Alloy which brings modern patterns to us. I loved it at first sight: it looked so MVC, and I felt so home. It took just a couple of hours to understand how it worked, the project structure was so self-explanatory and projects setup in no-time. I mean, just look at the file structure above: there’s everything you need to know.
As I dove into developing and get used by conventions, tricks and best practices, I learned how to get the most out of Alloy. But as soon as my code got clever, a question rose up: is this file structure really helpful?
Question: why this structure?
Alloy, like many MVC frameworks, follows the conventions over configurations principle, which means that there’s a contract between developers and the framework itself: you commit to name file properly and place them in the right location, and I handle everything else. That said, the title question doesn’t sound so silly, as file structure is the very base of the agreement. The followings are some spare thoughts I’d like to share about this topic:
Related files are far from each others.
Alloy’s UI entity is a triplet in the form (controller, view, style). This is reflected by the use of three files for each entity. But those triplet is spread across three different folders — controllers, views, styles. And that makes its files far. For example, in the image above, the file detail.js is closer to index.js than to its related detail.tss and datail.xml. This makes unpleasant to switch between files (although some environments let you do so by a keyboard shortcut), as well as do some operation like copy, paste, rename or delete a triplet. If you ever worked on complex app with 20+ entities, you know why I do consider this an issue. Not to mention, this approach doesn’t consider the principle of locality.
Lost of semantical connections.
Separation of concerns is a basic axiom of software design. Javascript developers implement this principle using the module pattern and the built-in require() function. In Titanium we can do the same, and Alloy wisely extended this behaviour with its entities. It’s a common — and best — practice to encapsulate related functionalities and UI components in different files, and than refer them either declaratively (<Require src=”myEntity” />) or procedurally (Alloy.createController(“myEntity”)).
This is very good, as let us write (and maintain) our code in a modular way. Pointed that, let’s add a further concept: our entities are also related each others in a hierarchy, which reflects the structure we thought for our codebase. In fact, it’s common to create entity to separate smaller sub-part of our UI (rows of a table, items of a list, etc.) or to reuse some functionality across our app (who said widgets?). Well, I think this aspect is actually messy in Alloy, as we can see that:
- Entities are stored in a flat way, there’s no mention to our hierarchy.
- Widgets are splendid for sharing components across multiple apps, but are sometimes overkill for sharing across the same app. More, there are some quirks that make them behave slightly different than a plain entity.
- A glance at an app’s file structure doesn’t tell nothing about the behaviour of the app itself. It actually tells a lot about the behaviour of the framework (models, controllers, views, styles, assets, migrations are actually top-level elements in the structure), and that’s probably the winning point of Alloy in terms of short learning curve.
Take a look at the image above: movie_cell (which encapsulate the TableViewRow component) is actually a sub-part of list.js (the TableView component), but there’s no mention of this relationship. Nothing to say about the widget nl.fokkezb.loading which is treated like a black-box.
A possible answer
Above issues didn’t impede to build efficient, maintainable and elegant software. What I think — and I’d like to discuss — is that we could achieve a better developer experience by just mind-shift our assumption on file structure. The image below represent a proof-of-concept of a possible new file structure for Alloy projects:
Here some key points:
- Each entity is placed into the /ui folder, and /controllers, /views and /styles folders are gone.
- Each first-level entity is placed in a folder with its name, for example /ui/detail. Thus, entities’ files are grouped by entity instead of by file type. This make them easy to move, rename, duplicate, delete or just copy&paste from a project to another.
- Sub-entities (entities that are sub-part of another, i.e. tablerows for tables) are placed inside the parent, so they are semantically bound to it (and the benefits from previous key point are even enhanced). In the example, movie_cell is bound to list both logically (our design logic) and fisically (the files paths).
- For each entity, index acts as an endpoint file. This is a parallelism with nodejs’ packages which enforces separation of concerns by “ideally” hiding other files from other packages. In the example, movie_cell is not meant to be referred by other entities, but only “locally” in the list entity.
- Widgets are at the same logical level of entities. And that’s right, because as mentioned in the official docs: “Widgets are self-contained components that can be easily dropped into Alloy-powered Titanium projects. They were conceived as a way to reuse code in multiple applications or to be used multiple times in the same application. Widgets have their own views, controllers, styles and assets and are laid out the same as the app directory in the Alloy project.”.
After our reengineering, there’s no more such a difference between widgets and entities, and we can achieve core benefits of the widget with the leanness of the entities. - Possibles enhancements: entities could encapsulate even assets or libraries, by consider local /assets and /lib folders. This would render entities even more independent by shipping themselves every part of the app that strictly belong to them (just like widgets do).
Conclusions
The purpose of this post was to explore new, potential enhancements over Alloy framework. I wrote it with my best intentions just offering my ideas and experience. Worth to say, I never meant to blame the actual state of Alloy nor ideas, concepts and decision taken by Alloy main designers and creators. Which craft a very good developer tool by putting in their best intentions. I just hope I spotted an interesting point of view, and this could help us get a better tool for our work.
After the conclusion
This solution — or a similar solution — can be achieved right now in at least two ways:
- By using an Alloy Makefile hook on pre-compiling. With some code it’s possible to transform a custom file structure into Alloy’s actual. This would be easy to implement, but will add extra time on each building roundtrip.
- By forking Alloy on github and replace the file structure logic. The codebase is well organized, thus it could be matter of few changes. However, this could be an overkill solution (and you have to keep up with updates by yourself).
References
- Example app: https://github.com/balanza/MoviesDemo
