CF New Mobile Project - Templates

You must be hearing about the mobile story in CF11, well yes, that is Huge. And if you haven't tried it yet, you are definitely missing a lot. Go on, try it but wait, don't you need a getting started tutorial. I bet you don't, only if you know that ColdFusion is providing templates for mobile project. Yes, you heard me right, templates. Isn't that great, you will get pre-baked code for your application. If you know what kind of application you want to create, just chose a template and wow! your application structure is ready. Alright, so now if you are interested enough to see how this works just read along otherwise still read along, I am sure you will feel like using it.

First thing first, this template feature is available in CFBuilder and being said that let me make you aware of the importance of CFBuilder3 with ColdFusion11. With CFB3 you will feel the actual power of mobile in CF11. Why is that? because with CFBuilder you can start right from scratch, use templates to create a mobile project, use builder's code assist to help you with new mobile functions, create a packaged application for iOS/Android, download it and install, DEBUG it from you device, inspect it with WEINRE and so much...

Now coming to the template feature, here are the steps you need to perform before you can try it.

1. Install CFBuilder3
2. ColdFusion server will be installed with it(if you opt for it while installation)
3. Start CFBuilder
4. Create a New Mobile Project

This is where you will see a template page. Just to get you familiar with, here is a screenshot.

Notice I have marked the areas of screenshot so it will be easier to refer them while explaining. I know the red markers look ugly but please bear with me. I'll explain area one by one

1. System Templates: These are the templates provided by ColdFusion. Right now there are only few templates but with future releases you may enjoy more templates here.
   Very first template listed is Blank. You can opt this template if you don't want to go with the other templates provided by ColdFusion. This template will create index.cfm in your project, with just cfclient tags in it and you are free to create app the way you want. This will be the default template selected every time you open this wizard.
   Second one is Master-Detail template. This is a pretty common and famous one in mobile devices. The index.cfm generated using this template will contain all the required code to show a basic master-detail UI in page/device-app. The settings page in smartphones is a very good example of such a layout. Initially you will get a list of items, called as mater page and on clicking on an item, you will see details about it, called as detail page.
2. User Templates: If you want much more than default templates, this is just the right section for you. You can create your own templates and use them every time you create a project. Even more, you can share it in ColdFusion community to let CF developers take full benefit of it. I will talk more about creating your own template in separate section.
3. Type: After selecting a template, this is where you can select the type using which you want to create the template. With each template there could be multiple types associated. There are many libraries available to create mobile apps like JQuery Mobile, bootstrap etc.. So it's possible to create same layout using different libraries which is why multiple types with each template. You can chose the one you like. By default the very first type listed will be auto-selected. Once you select the type, Next button in wizard will be enabled and you can navigate to next page.
4. Description: This is where you will read the description about the template. Description changes according to your selection of template and type.
5. Import: You can import the templates too, be that your self created template or community shared template. Once imported you will see the template added in User Templates section, chose it and create your project.
6. Next: Next button will be enabled if both the Template and it's respective Type is selected. By default Blank template and None type will be selected. Once done, navigate to next page.

Creating custom template
Before I start on creating custom template let me tell you that where these templates are saved. Both System templates and User templates are picked from this path: CFBuilder_installation_directory/templates/mobile/

You will see two directories in it, System and User. System directory is to keep templates provided by ColdFusion and the User one is to keep User templates. For further reference I will refer these as System Template directory and User Template directory.

At beginning User Template directory will be empty but System Template directory must be containing few templates. Though you can refer the the templates present in it but I will recommend not to change anything in it.

Templates are supported in both zipped and directory format. So let's start with the directory format because for zipped format all we need to do is zip the template directory. Follow the steps

1. Create an empty folder, give it a name of your choice(can be used as template name in case name not provided in configuration file).
2. Create config.xml file in it. Config file is used by CFBuilder to scan through valid templates and their information. Here is a sample code for config.xml
   • The name of the template will be picked from root element template attribute name. If name is absent then directory's/zipped-file's name will be shown as template name.
   • Description will be read from description element, child of root element. This description will only be shown if type specific description is missing.
   • type element inside types will be used for specifying type information. The name of the type will be picked form attribute value. The type description will be picked from description element present as child of type. If this description is missing then generic description will be shown.
   • You can give as many types as you want.
   • We map each type to a directory, so there should be a directory present in parallel to config file, with the same name you have specified in value attribute of each type. For this example there should be 2 directories present namely: JQuery Mobile and Bootstrap, each directory mapping to each type. Any extra directories kept parallel to config file will be ignored
   • If the directory is missing for a type then that particular type will not be listed in Type section.
   • On successful completion of project, the directory that is mapped to type will be exploded in your project. Files/Folders present in this directory will be copied to your project location.
   • There should be at least one type mentioned in config.xml with mapped directory present otherwise template will be considered as invalid.
3. As specified in previous steps create required directories parallel to config.xml
4. In directories(created in previous steps) create the files/folders you want in your project. If index.cfm is present here then on successful completion of project it will be opened for you automatically.
5. Place the directory you created in step one inside User Templates directory or you can use import feature of wizard. I will recommend to use import functionality, that way you will know if your template is valid or not. If your template is not valid and you have placed it in User Template directory by yourself, then your template will not be listed in wizard. 
6. To import you have to create a zip file of your template. Create a zip in a way that zipped file should directly contain config file and directories that are mapped to type.
7. From import section of wizard, press import, browse to zipped template you have created and wola! If it was a valid template then you will get successful message otherwise a descriptive error about the problem with your template.
8. Template that you imported in previous step will be copied to User Template directory, in case you want to check. And no need to close CFB or wizard, just after importing you can see your template right under User Templates.

After this I think you are good to go. Once you will create your project, you will see your template files in project and you can test it either by running it as ColdFusion application or creating a packaged app and installing it in device. For other details like packaging application or debugging it or inspecting it, keep looking for more blogs but I think this is good point for you to start. Go on now, build your apps.

-Milan.