IPad Presentation Development Guide
From Agnitio WIKI
The CLM iPlanner is a free app in the Apple AppStore and is distributed as any other iPad app. Upon first startup the CLM iPlanner will ask for login credentials and authenticate via a secure protocol with Agnitio's servers allowing the user to enter then main part of the application. Once authenticated, the CLM iPlanner can synchronize presentations, contact list and completed calls with Agnitio's servers, allowing the application to implement content material without it having to go through Apples AppStore while still maintaining the ability to execute presentations and manage calls while offline. The basis for content building is HTML5, thus any HTML, CSS and JavaScript can be used to build presentations and to enable detailed tracking within the presentation, there is a simple-to-use JavaScript API, which allows you to capture data from the presentation as you see fit.
Contents |
Architecture is the key
Put your text there!
Development Environment
Key in developing presentations for the CLM iPlanner is to note that, like Apple Safari, the rendering engine used in CLM iPlanner is based on WebKit.
Recommended development environment
- Development platform: Only requirement for the development platform is that is can handle HTML/CSS/JavaScript. Examples are Apple Xcode, Microsoft Visual Studio, Eclipse, or even a simple text-editor will do.
- Process and policy requirements: There are no requirements in regards to working with CLM iPlanner. Important to note is that there are no versioning of presentations in CLM iPlanner. Therefore any internal policies regarding backup routines, versioning, release management etc. must be handled by the development environment to the degree required.
- 1st level test: If the development platform used offers a dependable iPad simulator running Safari this might be the most optimal solution. If a simulator isn’t offered in the development platform used, it is recommended to use Apple Safari with the appropriate user agent selected (Select: Develop -> User Agent -> Safari iOS 3.2.2 iPad). However any WebKit based browser can be used for 1st level testing
- 2nd level test: iPad testing should be carried out in the earliest stages of development. Make sure the presentation is available through a HTTP server that can be accessed via WI-FI. Use the “Save to homescreen” feature in Safari on the iPad and execute from there, this will ensure that the presentation will be rendered almost exactly like in the CLM iPlanner.
- 3rd level test (final): To be 100% sure the presentation needs to be tested in CLM iPlanner, to do please use the provided Agnitio Manager and CLM iPlanner login credentials. Remember to place the index.html in the root level of the directory. It is highly recommended to carry 3rd testing as often as possible.
- Check list for iPad presentation test: This sample checklist is created for a generic presentation. Testing options should be decided on a project-by-project basis. Customization is needed according to the project scope. http://www.askagnitiodemo.com/download/Download-Link/AgencySupport/Check_list_for_ipad_presentation_test.xlsx
- Gap between 1st level and 2nd level test: While dealing with specific characters, Safari iPad browser might render text differently from the Safari desktop browser. Solutions: 1.Change system display language. 2.Use Unicode for special characters in your presentations. 3.Try different fonts.
- Gaps between 2nd level and 3rd level test: 1. Memory leak: iPad as a device has its own restriction on memory usage for each application – one major difference between 2nd level and 3rd level test is that all resources are restored and processed in the iPad, which takes much more memory. This topic will be covered in the Agnitio agency training. 2. iPlanner APIs dependent functionalities: Data monitoring, PDF opening and Email sending can only be tested on the iPlanner. 3. Failure in running presentation in iPlanner: iPlanner will prevent running a presentation if it catches critical Safari iPad browser errors, especially on missing elements. An “Error playing the presentation, please go to sync” message will be displayed under this scenario. Please refer to the corresponding topic in FAQ section below for detail description and solution.
HTML and CSS
The WebKit based browser in CLM iPlanner has a very high degree of support for HTML5, although the W3C recommendations isn’t in its final stage, for the best result it is highly recommended to use HTML5 in developing presentations for the CLM iPlanner. As for CSS it is highly recommended to CSS3, however some of the newest features/properties needs to be prefixed with “-webkit-” to be properly interpret by the browser.
Animations
Although it is, of course, possible to animate elements using JavaScript but performance is often very poor and slow on iPad, for smoother results, it is recommended to use CSS3 transitions.
For more info, visit: http://developer.apple.com/library/safari/#documentation/InternetWeb/Conceptual/SafariVisualEffectsProgGuide/Transitions/Transitions.html#//apple_ref/doc/uid/TP40008032-CH4-SW1
JavaScript
- Frameworks: Frameworks intended for the desktop browser work on the iPad, but they contain a serious overhead for dealing with browser differences, which are completely unnecessary here. The most common use of frameworks is to be able to select an element easily, and luckily on the iPad, it is possible to use
document.querySelector("#someId .someClass[attribute=value]")
or
querySelectorAll
for multiple elements.
If a framework is desired it is recommended to use a micro-frameworks like Zepto.js (http://zeptojs.com/). It uses a very jQuery-compatible syntax, so for jQuery familiar developers this is a simple switch. For creating scrollable, swipeable content it is recommended to write your own script. We do not recommend iScroll unless the developer has no choice.
- Events. As a touch device the iPad uses touch event, namely touchstart, touchmove and touchend. Regular mouse events are also supported, but for a more responsive presentation it is recommended to use touchstart instead of click.
For more info visit: http://developer.apple.com/library/safari/#documentation/appleapplications/reference/safariwebcontent/HandlingEvents/HandlingEvents.html
Monitoring / Analyzer
There are two steps you need to take in order to enable monitoring in your presentation:
- You need to refer to the built-in JavaScript file: ../viewer/js/monitor.js
- You need to set the variable monitoringEnabled to true: window.monitoringEnabled = true;
Although this feature cannot be tested outside the iPlanner, the monitor.js becomes available to presentations uploaded to the iPlanner ftp.
Please refer to our monitoring API and examples here: Agnitio_Monitoring_API_(iPad)
Note, that the monitor.js must be load from the root folder context of the presentation as the file have additional dependencies which are also loaded relatively.
References / PDF Viewer
The iPlanner actually includes a built in PDF viewer, so pdfs can be opened, browsed and when closed, the user continues right where they left off. To use simply add a script tag to the head of a file located in the root directory.
<script src="../viewer/js/pdf.js" type="text/javascript"></script>
In order to open the PDF call the javascript function, openPDF with the file path as parameter. Please note that the path is given originates in the root directory.
Ex:
openPDF('docs/PDF_document.pdf');
This feature cannot be tested outside the iPlanner and the pdf.js only becomes available to presentations uploaded to the iPlanner ftp.
Presentation Icon
In order to display a presentation icon inside the iPlanner presentation overview, place an image file called icon.png (220x64px) to the root level of your HTML archive.
Send emails
- You need to refer to the built-in JavaScript file: ../viewer/js/sendmail.js
Ex:
<script src="../viewer/js/sendmail.js" type="text/javascript" charset="utf-8"></script>
And then you could use the following APIs in the presentation.
function sendMail(address, subject, body, fileName)
Ex:
sendMail('email@address.com', 'subject message', 'body of mail', 'path to attachment');
- When you have a file attachment, please make sure the attachment is placed on the root level of the presentation, which is due to the default file referencing rule on the iPad.
FAQ
Why is my animation slow? Besides sheer complexity, there can be several reasons for this: Try to use CSS transitions for animations rather than JavaScript. Use translate3d instead of translate (translate3d is hardware accelerated). Avoid using opacity at the same time as other transitions if possible; opacity can interfere with hardware acceleration.
My presentation has no logo in the CLM iPlanner? Make sure you have uploaded the file called icon.png (220x64px) into the root level of the directory.
Why does my presentation crash? Most often this is a result of using too much memory. The first place to look are videos and images in the presentation.
Some images or other external files don’t seem to be loaded, why? Most often this is because of discrepancies in casing. Remember that CLM iPlanner is case-sensitive.
What image format should I use? This is a case-by-case decision. In most cases it is best to use PNG. Most important, besides image quality of course, is memory footprint, e.g. use the format that creates the smallest file.
What is the start or default file in the presentation? index.html in the root level of the directory.
Should my presentation be one or several HTML files? In general it is recommended to contain the entire presentation in one HTML file (index.html). Only if the size and memory use dictates it should the presentation be split into several files. We generally load page fragments so the presentations can be dynamic, so we always have many html files.
Error playing the presentation, please go to sync This error message indicates a failure in running presentation in iPlanner. It is usually caused by missing files or corrupted files in the presentation.
First of all, it is highly recommended to re-download the presentation with good internet connection in order to make sure that no file is missing during downloading process. To ensure a full re-download, please use the “Force Synchronisation” option in the Settings menu Please, refer to the scenarios below if the error is reproducible.
Scenario 1: It is caused by missing or corrupted file(s) in the presentation, which might have been blocked or corrupted during the transfer from FTP server to the iPad.
If the error occurs when starting a presentation, Scenario 1 most likely applies.
Solution: Firstly, double check PDF files and ‘unusual’ file formats in the presentation. Removing all ‘suspected’ files from the FTP, and try if it solves the problem. A best practice is always to exclude files that are not used in the presentation.
Scenario 2: It is caused by referring to a non-existing element when starting the presentation.
If the error occurs during the presentation, Scenario 2 most likely applies.
Solution: Under this scenario, developers could expect to capture a "Failed to load resource" error in the desktop Safari browser.
Agnitio agency support desk will be happy to help agencies in solving this issue upon request. According to Agnitio’s agency support policy, if the reported issue/problem isn’t an error on Agnitio’s side, an additional cost will apply to the support request. Since the underlying problem behind this error is either on the iPad (iOs) or the presentation programming, Agnitio’s standard agency support policy will apply. However, if the reported issue/problem turns out to be an issue with the Agnitio software, Agnitio will naturally absorb the cost of remedying the error.
