What’s In A Name? Cordova is known by a few names, partly because it’s changed over time and partly because several companies offer Cordova bundled with their own tools to help with using it. To keep things general I’m just talking here about the core component in PhoneGap, Ionic, and others which is called “Cordova”.
Why Would You Want To Update A Cordova App? A lot of people are getting custom apps made now. Perhaps you got achieved your funding goal on KickStarter or IndieGoGo or GoFundMe and your idea involves an app. If you got it built and asked for it to be cross platform (say, Android and iOS) then you were probably given a Cordova app from your developer.
Maybe you’re reading this because you’d just like a better understanding of what it is you were given.
Maybe there are typos and other minor mistakes and you’d like to save money by fixing those yourself.
This should help to get you started.
Anatomy of a Cordova App Cordova projects have a specific structure of folders. Some folders are “source”, which Cordova reads from to learn what you want done. Other folders are “targets”, which Cordova writes its output to. If you edit files in a “target” folder your changes are likely to be over-written down the line, which could get frustrating (but at least you kept a backup, right? Right?)
Here’s how a Cordova project fits together (click for full size):
Your developer will have hooked you up with a source repository in Github or BitBucket or Beanstalk or some other tool that stores source code. To get a current copy of your source code to play with, you’ll need to “check out” or “clone” the main branch which might be called “master” or “trunk”. The terminology varies between systems (for no good reason) so hopefully your developer will advise you on the details.
What this might look like:
Once you have cloned or checked out a copy of your source code, you can start to explore what code is there. Cordova apps will have a “www” folder front-and-center in the source folder. If you find other “www” directories under a “platforms” directory, leave those alone as they are automatically created meaning Cordova might overwrite any changes you make there.
Welcome to your app! This “www” folder is the primary source code for your app. It is easily the most important folder of them all.
You may or may not realise this, but Cordova apps are web apps. Cordova takes a web app from your www folder and packages it up to look like phone apps for each platform, including its own custom web browser to help it look like any other app and allow access to phone hardware that ordinary web apps might not get. That’s why the name “www”, short for “world wide web".
When you want to make an update to your app, you’ll typically start here by editing a file or two.
Types of file here are:
• .html files: Describe the structure of “pages” in your app, marking out where information is to be filled in and what text is always there. Kind of like a form.
• .css files: Defines re-usable visual styles that your .html pages can draw from. This is often where colours, fonts and details of the “look” of your pages are defined.
• .png, .jpg, .svg files: These are images that can be used by your pages. They might be icons, your logo, splash screen images etc.
The merges folder
Most parts of a Cordova app are simply cross platform so you only need to describe a page once in the www folder, and it’ll be used across iOS, Android etc.
The merges folder is all about exceptions to this rule. If a page in your app needs to be different in iOS vs Android, perhaps a page of instructions with different pictures for each, then the “merges” folder would have just those files that need to be replaced on a per-platform basis. For example, to replace an image file from www/img/phonePicture.jpg with a picture of an iPhone for the iOS platform, you’d put the alternative picture for iOS into merges/ios/img/phonePicture.png. Only the iOS build of your app would receive the changed picture.
The platforms folder
This is where Cordova creates a full version of your app for each platform. There is a folder here for each platform you’re building, for example you might have platforms/android and platforms/ios if you’re just building apps for iOS and Android. These can be added, removed and updated by Cordova so it’s best not to edit what’s in them yourself. Let Cordova handle that.
What you may need these folders for is to build and test your app. Building the app can be done from the command line, but if you’re like me then you find it a bit easier to use a graphical environment to test and publish your updated app.
Prerequisites To Make Changes
• node.js -
• cordova - run from the command line,
$ npm install cordova
• xCode to build for iOS (Mac only) - App Store
• Android Studio to build for Android -
Each part will probably need to be fairly up-to-date as these tools are under constant development.
Testing Updates In A Browser
The quickest way to test an app is to use the “browser” platform to simply run your app in a web browser from Cordova, without installing it on a mobile device at all.
If /platforms/browser doesn’t exist yet, you’ll need to add it. This should be only needed once:
$ cordova platform add browser --fetch --save
Then tell Cordova to run your app for web browsers:
Leave that running in its window and point your web browser to the green part: http://localhost:8000
If your changes aren’t so good and you need to edit files again, do so (in the correct www directory) and update what’s being served using:
$ cordova prepare browser
Then hit refresh in your browser and you should be seeing the new version.
Testing Updates In Xcode / Android Studio
When it comes to installing your app on real phones and publishing it to stores, the most obvious way is to run it using Xcode (for iOS) or Android Studio (for Android).
This is similar to running the code in a browser:
Check if /platforms/ios or /platforms/android exist. If not you’ll need to add whichever is missing:
$ cordova platform add ios --fetch —save $ cordova platform add android --fetch --save
If it already exists, update it using
$ cordova prepare ios
$ cordova prepare android
Then open the project file in Xcode, it will be named like /platforms/ios/MyApp.xcodeproj
or for Android studio, you’ll want to “import” (not “open) the platform/android folder itself.
In both Xcode and Android Studio you can launch your app (look for a “play” ▶️ button). You might have to select a platform to run on, this can be a simulator (a pretend phone that shows up on your computer screen) or on a real device, which you’ll need to plug in to your computer using its cable.
Remember that git / subversion repository at the start where you got the source code from? Now you have a new version of your app you’ll want to save that back.
Your developer will be able to provide you with instructions for the platform you’re using. With Subversion you’re asking them how to “commit” a change, for Git you’ll need to ask how to “commit” and “push” as well.
Make sure the changes you “commit” are the ones from the /www (or /merges) folders not the ones from the “platforms” folder, as platforms are generated files and not part of the original source code.
Once you get started you’ll most likely get stuck in various places. Ask for help when you need it, or use google to find more in-depth resources about each area.
is a great resource with question-and-answer style information about all kinds of Cordova issues.And most of all - have fun!
To help with communication and visibility about where we are in a project together, I use a web application called Trello.
The Trello board for your project will have a column for new discussion, a column for documentation like where your servers are etc, then the main part: a column for each stage of the project. ￼
Each column contains “cards” which each describe a step in our project’s journey. We will add and change cards as needed because each project is unique. We’ll try to fit one clear idea on each card so they can be documented and discussed individually.
Each card in Trello has two “sides”: the front is a short summary of the card like this:
Click a card to see the “back” of the card. Surprisingly the back is much bigger than the front: ￼
The back has as much information as we want, and importantly it has an area to add comments so if you need clarification about a card or want me to remember something about that card, you can add a comment right into that step of the project. I’ll handle managing the cards for the most part, so you can simply glance at the board to see where I’m up to and “comment" as needed.
See you in your custom Trello board!
I don’t actually get a lot of questions about how to choose a developer, perhaps because people will assume bias. So lets get past that quickly: of course you should hire me, I’m awesome!
Now we’re past that, let’s assume that I’ve met, interviewed and worked with quite a few developers good and bad. Let’s assume that I regularly “rescue” apps where the owner regrets that they hired “The Wrong Developer”.
Software development can be a topsy-turvey kind of affair, with words that should mean one thing but really mean another.
“Choosing a Developer”: a weird kind of job interview where the employer (you) attends the offices of the potential employees, and are given coffee, comfortable (or condescending) chat, and perhaps a glossy bid brochure. **Therefore 1: **Keep your wits about you, and remember you’re the interviewer. Make sure they can handle simple questions, that their communication is clear. **Therefore 2: **If you’re at an AGENCY then you might be interviewing one person to help with project communication but really hiring another to do the work. Ask about which individual will be your key “hands on” developer and see if you can interview them specifically.
“Source code”: **This is the specification of what your app should do, laid out in painstaking mathematical detail for a computer. **Therefore 1: However amazingly you’ve prepared your specification, if it’s not source code yet then there are gaps. There are cases, conditions and “gotchas” that you will need the developer to fill in when translating your idea into source code. Importantly, your specification is a guide only. There will be gaps to fill and changes you haven’t thought of. **Therefore 2: ** Your developer needs to understand you, where you’re coming from and what you hope the app will be like to use to fill these gaps in the ways you’d hope. If your end user does something wrong or unexpected, you probably hope for the app to respond in a helpful non-crashy way. No amount of pre-planning short of writing the app itself can cover every case that a developer will see. **Therefore 3: **There will always be unknowns that you haven’t planned out. This means time estimates are genuinely hard. Most people are bad at estimating time, and will be out by a fair bit. Sure there are some unscrupulous people who do this deliberately to get you in the door, but in general people just forget the extra time needed to polish out those last few glitches, test it on a few more devices, etc. You just need to allow for more time than what people say.
**“90% Complete”: **This means 50% complete. In the words of Bell Labs’ Tim Cargill, “The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time” (wikipedia). As mentioned previously, it’s so easy to under-estimate how long those loose ends will take.
Given these definitions, what does The Wrong Developer look like?
1. The Wrong Developer is confident. They promise big and all within your budget. It's almost "too good to be true". 2. The Wrong Developer is just the "communication person" who one or more developers hide behind. Double points if their "team" is overseas and inexpensive, as you can guarantee communication difficulties. 3. The Wrong Developer wants to take your project in another direction and you have to keep reigning them in. 4. The Wrong Developer doesn't believe in handing over Intellectual Property – because of course you'll stay with them! They hold onto source code or copyrights. 5. The Wrong Developer doesn't need to know the details to give a quote 6. The Wrong Developer doesn't have a plan to adapt their pricing as your needs change. And yes, your needs will change. 7. You won't quite "click" with the Wrong Developer. Communication will be irregular and hard to understand. You just won't have "chemistry" with them and find them hard to trust. 8. The Wrong Developer will know or not know the tools needed upfront, with no sense of "Yeah I can learn that". 9. The Wrong Developer has never worked on an app of this scale before. You ask about their portfolio and they say "ah that doesn't matter, I got this". 10. The Wrong Developer won't plan regular meetings with you. 11. The Wrong Developer isn't really that interested in whether your app is a success; its just another thing to do. 12. The Wrong Developer evades rather than leading talk of testing and documentation.
Conversely, the right developer will be someone you can talk to. They’ll not only be open to change but will be like a collaborator, making suggestions and showing they “get” what you’re trying to achieve. They’ll talk to you through the ups and downs of building the project, so you know where things are at and when they’re stuck on something. You’ll be clear what they need from you, and have similar values to you regarding the quality and feel of the app you’re building. They’ll understand that the app is YOURS, in terms of final decisions and intellectual property rights. They’ll suggest ways to handle testing and be able to discuss what kinds of documentation would benefit you. Communication, trust and expertise are the three keys. Get those right and you’re putting your best foot forward.