The WWW or web code is inherently cross-platform (assuming web standards are followed) and should be the same on all platforms. Where necessary, different code paths can be built for specific devices, though this is usually only necessary when talking to certain third-party plugins that are specific to certain platforms.
The native code initializes any native plugins as well; these can be core plugins provided by the Cordova team, third-party plugins developed by other members in the community, or custom plugins developed internally by the enterprise. This is a major benefit of using Cordova; if a particular feature isn't best handled or possible using web technologies, there can be a plugin developed by someone else that implements this feature. If there isn't such a plugin available, it's usually pretty easy to create such a plugin internally.
The following diagram provides a bird's-eye view of how each layer talks to one another:
A typical Cordova app has the following structure on the filesystem:
A typical Cordova project has a config.xml
file in the root directory of the project that specifies the name, description, and other attributes for the project. There can be other files (such as a build script or a readme
file, indicated by an asterisk in the previous diagram) that are also project-specific and internally developed by the enterprise to support the project. (If you want to see examples of these additional files, feel free to look at the code package for this book.)
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
All of the web code is put in the root www
directory. There are other www
directories in other various subdirectories (in the platforms
directory); however, these are all duplicates and should be considered build artifacts (they are overwritten each time the project is built). As such, don't commit the platforms
directory to your Version Control System (VCS).
The structure of the root www
directory is specific to the project under development, and the various frameworks and libraries being used. The example in the preceding diagram is a portion of my typical directory structure within the www
directory. Ultimately, there is neither a preferred nor mandated structure within this directory.
The hooks
directory might not exist, and it should only be used if you need to perform custom actions when specific events occur in the project. For example, you might need to create a hook that notifies an external build system that the app's build was successful; such a hook will be created in this directory.
The merges
directory is another directory that might not exist and it should be avoided if at all possible. The original intent was to provide a way to override code in the www
directory with platform-specific www
code. If this code is correctly written according to the various web standards, then it is rarely necessary to use this functionality. If your app needs to behave differently on different devices, it is better to detect the device and branch appropriately.
The platforms
directory includes every platform added to the project. As new platforms are added, native wrappers are created within this folder, and the www
directory gets duplicated within these wrappers. Essentially, one should consider this directory a build artifact and it should never be checked into VCS.
The plugins
directory includes every plugin added to the project. Similar to the platforms
directory, it should be considered a build artifact and should never be checked into your VCS. The plugin management should instead be managed using the CLI or a shell script. If you want a good example, please check out the code package for this book.
None of this details how the www
code should be structured or what architecture it should use. Cordova is not prescriptive in this regard—you can leverage your knowledge of the existing web frameworks (such as jQuery, Sencha Touch, and so on) and other libraries (such as Underscore, Backbone.js, and so on).