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.
This cross-platform web code is wrapped by native code. This code is specific to each platform the app supports (and so the app can only run on platforms supported by Cordova). This native code serves to bootstrap the app and instantiate a single full-screen system browser in which the web code is executed.
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 native code also provides a bridge, or interface, between the native plugins and platform, and the web code. This bridge provides the mechanism by which the web code can access native device features by providing a simple and consistent API. This enables a web code to talk to specific plugins in order to perform native device functions.
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.
Note
Hooks are beyond the scope of this book as they are highly specific to each enterprise and app. However, there is a lot of information available online. The documentation at https://github.com/apache/cordova-lib/blob/master/cordova-lib/templates/hooks-README.md would be a good starting point.
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).