Ayuda en línea 1. Overview 1. 1. Overview
2. Plugins Documentation 2. 1. Plugins Overview 2. 1. 1. Custom sections overview GoodBarber allows you to create your own sections, using HTML5. There are 2 types of custom sections, with 2 levels of complexity:
Basic custom sections (low complexity, and limited possibilities) HTML5 Plugins Sections (coding required, high customisation possibilities)
1. Basic custom sections The Custom section is a section using HTML to allow you to display rich, static content. It's cached into the app, which means that it's available when there's no connection. You can use pre-definied templates to manage your custom section, or directly modify its HTML code. It is possible to display dynamic or distant contents, using the HTTP template, hosted on your server. Usage (example) : display display a presentation page, give some contact informations Complexity : Low Low Interactions with the rest of the app : Basic Basic Quality : Good Good
2. HTML5 Plugins Sections The HTML5 Plugins sections are sections that can contain your own source code, specifically developed for GoodBarber. The Plugin development need an expertise in HTML/JavaScript, and a strong knowledge of the specifications. A good knowledge of the mobile development practices will help you. The HTML5 Plugins sections will allow you to enrich your app with features regarding your specific needs. Usage (example) : develop develop your own section based on a custom data source, integrate a quizz or a survey, etc. Complexity : High High (web skills + mobile + knowledge of GoodBarber) Interactions with the rest of the app : High High Quality: Native-like Native-like
3. Some advices When you think about integrate a customized section into your app, think about the features and the level of customization that you will need. The HTML5 plugins will allow you to enrich you app, but will be more complex to develop than a basic Custom section. It will also need to be maintained along the life of your app. Always keep it simple!
2. 1. 2. HTML5 Plugins Overview 1. Plugin overview An HTML5 plugin for GoodBarber is a bundle of HTML/Javascript files, and several assets which will be cached into the app and executed directly in your app. An HTML5 plugin section will appear as the other sections in your app: - It will be displayed between the Navigation Bar and the bottom of the screen, or the TabBar, according to the navigation mode you choosed - By delegating its internal navigation to the app, the plugin will benefit of the same transition effects (horizontal push, modal) than the other sections - By delegating its cache management and its network interactions, the plugin will be available available offline - It will also have the capability to interact with the rest of the app (send and receive messages)
2. Content of the plugin bundle Your plugin can contain several types of files: - An index.html file (mandatory) that will be the plugin's main page - Other HTML files (optionnal) that would be the plugin's other pages - Other resource files (optionnal), like images, CSS stylesheets, JS librairies, etc.
All the dependancies to the plugin files have to be made in the current directory (./).
3. How to send and receive message to and from the app There are two types of interactions possible between your plugin and your GoodBarber app. Messages sent by the plugin to the app (Plugin => Native) The plugin can send messages to the app, by starting a navigation to documented URL schemes. These methods can be used to manage the internal or external navigation of the plugin, to manage the network interactions, and other methods. Messages sent by the app to the plugin (Native => Plugin) These are JavaScript methods sent by the app on the plugin. It can be callbacks sent in response to methods called by the plugin, or methods called by the app according to the lifecycle of the app. The plugin has to implement the JavaScript methods of the callback protocol that it needs to handle. The implementation process of the methods and callbacks of the GoodBarber Plugin API is described in the article Plugin API Overview.
4. GoodBarber JavaScript ToolKit The methods available to discuss with the app (navigation, download, etc.) can be called directly by sending HTTP request to the app. However, in most cases, you may prefer to use the GoodBarber JavaScript ToolKit that makes the calls easier, with an encapsulation of the requests into JavaScript functions. In this documentation, you'll find the method prototypes in the HTTP requests version, and their equivalent in GBJSToolKit .
2. 2. Plugin API Documentation 2. 2. 1. Plugin API Overview (Methods & Callbacks) The GoodBarber Plugin API allows you to directly utilize the available interaction methods with the application.
1. Exchange Principle Plugin => Native => Plugin The method calls from the plugin to the application are made by triggering a web navigation to a particular URL. The callbacks are performed through JavaScript method calls to the plugin.
2. Method Cals (Plugin => Native) All method calls of the GoodBarber API Plugin must be performed by triggering a web navigation. This navigation may be triggered in several ways: - Clicking on a link - Calling a document.location () in JavaScript - Submitting a form
Please note: Ajax requests (XMLHttpRequest) are not considered as triggering a navigation and can therefore not be used for method calls of the GoodBarber Plugin API. The majority of available methods (apart from the "basic" methods described in the documentation) must trigger a navigation to a URL beginning with goodbarber://, followed by the name of the method to call and other parameters. With a few exceptions, the arguments muss go directly through the URL, but in some instance, especially for navigation methods, POST arguments may be used. Pour déclencher simplement des requêtes POST depuis du code JavaScript, utilisez la méthode gbPostRequest à votre disposition dans le [GoodBarber JavaScript ToolKit]url: . To trigger POST requests from the JavaScript code, use the gbPostRequest method in the GoodBarber JavaScript ToolKit.
3. Calls and implementation of callbacks (Native => Plugin) Callbacks are prototypes of JavaScript functions to be implemented in your code. It is very important to respect all specifications so that the information is exchanged correctly. In the documentation for the GoodBarber Plugin API, you will find the definitions of the callbacks that can be implemented, as well as an example of implementation.
Callbacks can be called by the application for two main reasons: - A method call requiring a response - During the life cycle of your plugin (methods documented in the Events Callbacks section)
4. Data accessible by default In all of the pages of your plugin, you will have access to two JavaScript dictionaries.
gbUserInfo Contains information on the terminal, the OS, etc. { "platform" : "ios" | "android", "binaryVersion" : version of the application's binary, "gbVersion" : version of the GoodBarer foundation , "osVersion" : version of the OS terminal , "deviceCode" : code name of the terminal (for example : "iPhone5,2"), "iPhone5,2"), "language" : user language }
gbPostData Contains a dictionary of the parameters in POST following the call of the preceding method, in the case of navigation methods. { ... }
2. 2. 2. Basic methods In your GoodBarber HTML5 plugin, you can use "basic" methods, allowing interactions with the user's device. These methods are also available in the Basic Custom sections. Most of the basic methods can be called by launching a navigation to a standard URL scheme. They're also available, in an easier way, in the GoodBarber JavaScript ToolKit.
1. Web Browser Navigation (http://) If you want to start a navigation to an external URL - typically a web link- you can just call the link. The http:// prefix will be interpreted by the app to be opened in the internal browser. Example of a link to Google within a plugin:
Go on Google
2. Mail Composer (mailto:) Il you want to open the phone's Mail app composer, to allow your users to send an e-mail from your plugin, you just have to launch a navigation towards a mailto: scheme. According to the standard, a mailto: link can handle several parameters (to address, subject, body, etc.). Example of mailto: link within a plugin:
Send an e-mail
3. Call (tel:) If you want to start a phone call within your plugin, you can use the URL prefix tel:.
Warning: There are no alert before the phone call starts using the tel: method. If you want to ask your user for a confirmation, you'll need to implement a confirmation alert. Example of phone call within a plugin:
Call +1 (555) 555-5555
4. SMS Composer (sms:) If you want to open the phone's SMS composer within your plugin, you can use the URL prefix sms:. It is unfornately impossible to set the SMS body, but you can set a default recipient. Example of SMS within a plugin:
Text +1 (555) 555-5555
5. Maps Link The maps method allows to open directly the Maps native app on the user's device, with one or several parameters. The parameters to include into the URL are the one which usually follow URLs like "http://maps.google.com" and "http://maps.apple.com". You can find more information about these parameters in the Apple reference documentation. The maps method allows you to send seamlessly the user to the dedicated native app of his device ( Maps on iOS, Google Maps on Android). If you want to send your users to a specific app (without the automatic choice), you can directly make a link to the destination URL that will be opened into the in-app browser. Example of the maps method usage:
Locate "Cupertino"
6. Method : openapp (Open an app, or a link) The openapp method allows you to open a custom URL scheme, if an app able to open it is installed on the user's device, and to open a web URL if not. URL parameters: - scheme : the custom URL scheme of the app to be opened (has to be url encoded) - url : the URL to open if the device can't handle the URL scheme Example of the openapp method usage:
Open Twitter app if it's installed, or go to the website otherwise
the
7. Method : openExternal (Open an URL in the external browser) The openExternal method allows you to open the phone's browser (and leave the app). URL parameters: - url : the URL to open Example of the openexternal method usage:
Open this link in the external browser
8. Method : gotosection (Go to a section) The gotosection method allows you to make a link to another section of your app. URL parameters: - id : the section identifier
NB : To find your sections ids, go to the Developer section of your GoodBarber backend. Example of the gotosection method usage:
Open the news section of the app
2. 2. 3. Navigation methods Your plugin has to delegate its navigation to the app. To do it, it will send messages to the app, using pre-defined methods, which will allow to pass arguments between its pages.
1. Method : navigate.push The push navigation is the basic transition (left to right) between two pages of your app. It is typically used to navigate from a list of content to the detail view of an item. Parameters to be passed in the URL : - page : the .html file to link to, has to be in your plugin's bundle It is also possible to intergrate POST parameters in your request, that will be accessible in the destination page as JavaScript variables. To pass POST arguments with a JavaScript navigation, use the GBJSToolKit. Example of navigation without POST parameters:
Go to the detail page Exemple of navigation with POST parameters, using the GB JS ToolKit:
Go to the detail page
2. Method : navigate.modal The modal navigation is a vertical transition mode between two pages of your app. It is typically used to enter a settings screen. Parameters to be passed in the URL : - page : the .html file to link to, has to be in your plugin's bundle It is also possible to intergrate POST parameters in your request, that will be accessible in the destination page as JavaScript variables. To pass POST arguments with a JavaScript navigation, use the GBJSToolKit. Example of navigation without POST parameters:
Go to a modal page Exemple of navigation with POST parameters, using the GB JS ToolKit:
Go to a modal page
3. Method : navigate.back When your plugin has made a navigation to another page, it is possible to go back manually. To do it, you have to call the navigate.back method, without arguments or parameters. Exemple of back navigation:
Go to the previous page
2. 2. 4. HTTP Request method and callbacks It is recommended that your plugin delegate the management of it's downloads to the application; and it is in fact necessary to do so to benefit from the authentication mechanism of the GoodBarber API calls. By using the download method, you can benefit from the application's automatic cache system. When you request access to a remote resource you may specify if you wish to receive a version of the resource that was previoulsy cached. Following a download method call, your plugin may receive one of the following callbacks:
- gbRequestDidFail ( tag, errorCode, errorMessage ) - gbRequestDidSuccessWithCache ( tag, data, src ) - gbRequestDidSuccess ( tag, data, src )
1. Method : request The request method simply allows you to request access to a remote resource. You must specify the following parameters: - url: The URL of the resource you wish to access (must be URL encoded) - tag: a tag (integer) to identify your request YES if you wish to receive a cached version if cache: callback gbRequestDidSuccessWithCache, gbRequestDidSuccessWithCache, otherwise otherwise NO - method: (optional) the HTTP method will be used in the request (default value: GET)
there
is
one,
via
the
You may call this method with POST parameters, that will also be passed on to the body of the request. Example of the download of a JSON stream in GET with a request for a cached version, if there is one:
Télécharger le JSON Example of the download of an image in GET without callback for a cached version:
Télécharger l'image
2. Request pathway
3. Callback : gbRequestDidFail The callback gbRequestDidFail is called if the request fails. It is strongly recommended to implement this callback method to correctly handle request fails. The method must include three parameters: - tag : the tag (integer) defined at the call of the request - errorCode : 0 if there is a network problem, the HTTP error code otherwise - errorMessage : a description of the problem leading to the request failure
4. Callback : gbRequestDidSuccessWithCache The callback gbRequestDidSuccessWithCache is called immediately before the beginning of the HTTP request if the called resource is present in the application's cache (and the request was called with the cache parameter set to YES). The method to be implemented must contain three parameters: - tag: the tag (integer) defined at the request call - data: the raw data of the resource - src: the pathway to the resource in the file system
5. Callback : gbRequestDidSuccess gbRequestDidSuccess The callback gbRequestDidSuccess is called in case of a success of the HTTP request. The method to be implemented must contain three paramters: - tag: the tag (integer) defined at the request call - data: the raw data of the resource - src: the pathway to the resource in the file system
2. 2. 5. Other methods In your HTML5 plugin for GoodBarber, you can use methods that allow you to access a certain number of "advanced" features of the application or terminal. The majority of these methods send a JavaScript callback indicating the success or failure of the method.
1. Method : authenticate You may request that users identify themselves to access a feature, through an "authenticate" method call. In this instance, you may specify which services (Facebook or Twitter) you wish to use for authentication. Arguments in the URL:
|facebook|twitter - skip: possible values:: YES (by default, allows the user to abandon the login process) | NO (force the user to log in) - services: possible values: all (by default)
If the value "all" is given for the services parameter, a transparent design is added to plugin view to ask the user through which service they wish to authenticate. If the parameter skip is not given (or set to YES), a button will allow the user to abandon the login. If the value is NO, the user will be forced to choose a service to log in. If the user is already logged in to the app through at least one of the services in the application, the login action will be transparent. When the authentication process is finished, two callbacks can be called: - gbDidSuccessAuthentication ( socialUser ) - gbDidFailAuthentication ( errorMessage ) Example of an authentication request through one of the services (without distinction)
S'authentifier Example of an authentication request through Facebook only:
S'authentifier via Facebook Example of an authentication request via one of the services (without distinction, authentication mandatory):
S'authentifier
2. Callback : gbDidSuccessAuthentication gbDidSuccessAuthentication The callback gbDidSuccessAuthentication is called if the authentication succeeded. The parameters regarding the user are stored as a callback parameter, via a dictionary.
The method to be implemented must contain a parameter: - socialUser: a dictionary containing the information pertaining to the authenticated user (the format is described in the following) Format of the dictionary in the parameter socialUser: { "serviceType" : "facebook" | "twitter", "id" : identifiant de l'utilisateur sur le service , "profileUrl" : url de profil de l'utilisateur , "username" : nom d'utilisateur (username), (username), "name" : nom (real name) de l'utilisateur , "profilePictureUrl" : url de la photo de profil , "gender" : genre ("male" | "female"), "female"), "birthdate" : date de naissance , "language" : langue parlée par l'utilisateur , "location" : localisation de l'utilisateur renseignée sur le service , "nbConnections" : nombre de connexions de l'utilisateur (amis ou followers), followers), }
3. Callback : gbDidFailAuthentication The callback gbDidFailAuthentication is is called if the authentication fails (typically if the user has not consented to the authentication). The method to be implemented must contain a parameter: - errorMessage: a message describing the cause of the authentication failure
4. Method : share You may use the share method to make sharing content in the social networks easy for your users, directly from the sharing module integrated into your GoodBarber app. Arguments passés dans l'URL : - text : le texte à partager (doit être URL encodé) - link : (optionnel (optionnel ) le lien à partager (doit être URL encodé) Arguments in the URL: - text: the text to be shared (must be URL encoded) - link (optional): the link to be shared (must be URL encodedExample of a share module with text:
Partager un texte Example of a share module with text and a link :
0plugin%20!&link=http%3A%2F%2Fwww.goodbarber.com"> Partager un texte et un lien
5. Method : getmedia The getmedia method allows you to call a terminal to obtain a photo or a video. You may restrict the type of content that you wish to obtain via this method, as well as the source (direct capture or choice in the albums). Arguments in the URL : - type : possible values : photo (by default) | video - source : possible values : all (by default) | camera | library If the value of the parameter source is left empty or set to "all" (default value), a menu will ask the user to choose if they wish to take a photo (or video) directly, or if they wish to choose one from an album. The value of the parameter type is transparent to the user: the user can only choose the corresponding media in the selection menu.
When the authentication process is finishes, two callbacks can be called:
- gbDidSuccessGetMedia ( data, src ) - gbDidFailGetMedia ( errorMessage ) Example of a method call getmedia: (asks the user for a photo, distinct from the camera)
Capturer ou choisir une photo Example of a method call getmedia (opens the camera)
Prendre une photo Example of a method call getmedia (request to choose a video from an album):
Choisir une vidéo
6. Callback : gbDidSuccessGetMedia gbDidSuccessGetMedia The callback gbDidSuccessGetMedia is is called if the media retrieval was successful. The method to implement must comprise two parameters: - data: the raw image or video data - src: the pathway to the resource on the drive
7. Callback : gbDidFailGetMedia Le callback gbDidFailGetMedia est est appelé si la capture du media a échoué. La méthode à implémenter doit comporter un paramètre : - errorMessage : un message décrivant la cause de l'échec The callback gbDidFailGetMedia callback gbDidFailGetMedia is is called if the media retrieval failed. The method to be implemented must contain a parameter: - errorMessage: a message describing the reasons for failure.
8. Method : getlocation The method getlocation allows you to call the terminal to obtain the user's geolocation data. This method does not require any arguments. It may send one of two callbacks: - gbDidSuccessGetLocation ( lat, long) - gbDidFailGetLocation (errorMessage)
9. Callback : gbDidSuccessGetLocation gbDidSuccessGetLocation The callback gbDidSuccessGetLocation is is called if the geolocation of the user succeeded. The method to be implemented must contain two parameters: - lat: latitude of the user - long: longitude of the user
10. Callback : gbDidFailGetLocation The callback gbDidFailGetLocation is is called if the geolocation of the user failed. The method to be implemented must contain a parameter: - errorMessage: a message describing the reason of the failure
11. Method : gettimezoneoffset gettimezoneoffset
The method gettimezoneoffset allows you to call the terminal to get the time difference between UTC time and local time, in minutes.
It will send one callback : - gbDidSuccessGetTimezoneOffset ( offset )
12. Callback : gbDidSuccessGetTimezoneOffset gbDidSuccessGetTimezoneOffset The callback gbDidSuccessGetLocation is is called when the difference is got.
The method to be implemented must contain this parameter:
- offset: time difference between UTC time and local time, in minutes
2. 2. 6. Events callbacks Events callbacks are called by your plugin as a function of the App Lifecycle and the user's actions (when content is shown, when the app goes into background mode or is retrieved from background mode, etc.) They are designed to help you manage the display of your content at the right time. Even if they are not useful all the time, it is nevertheless recommended to implement them to optimize the user experience.
1. Callback : gbAppWillEnterBackg gbAppWillEnterBackground round The callback gbAppWillEnterBackground is is called when app goes into background mode. Example of implementation: function gbAppWillEnterBackground() { // Do something }
2. Callback : gbAppDidBecomeActive gbAppDidBecomeActive The callback gbAppDidBecomeActive gbAppDidBecomeActive is is called when the app comes back from background mode. Example of implementation: function gbAppDidBecomeActive() { // Do something }
3. Callback : gbPluginDidLoad The callback gbPluginDidLoad is gbPluginDidLoad is called when the plugin finishes loading. Example of implementation : function gbPluginDidLoad() { // Do something }
4. Callback : gbViewDidLoad The callback gbViewDidLoad is is called when the current view finishes downloading. Implementation example: function gbViewDidLoad() { // Do something }
5. Callback : gbViewWillAppear The callback gbViewWillAppear is is called just before the current view is displayed on the screen. Implementation example: function gbViewWillAppear() { // Do something }
6. Callback : gbViewDidAppear The callback gbViewDidAppear is called just after the current view is displayed on the screen. Implementation example: function gbViewDidAppear() { // Do something }
7. Callback : gbViewWillDisappear The callback gbViewWillDisapper is is called just before the current view disappears from the screen. Implementation example: function gbViewWillDisappear() { // Do something }
8. Callback : gbViewDidDisappear The callback gbViewDidDisappear is is called just after the current view disappears from the screen.
Implementation example : function gbViewDidDisappear() { // Do something }
2. 3. GoodBarber JavaScript ToolKit 2. 3. 1. GBJS ToolKit Overview To use the GoodBarber plugin API, you may use the GoodBarber JavaScript ToolKit. This is a collection of utility functions in JavaScript that can be used to facilitate the use of certain methods of the plugin API. You will find three main types of tools: - Debugging parameters (activating alerts, deactivation of requests, etc.) - Various utility functions (contruction of URLs, sending of GET and POST requests, etc.) - Encapsulation functions of the GoodBarber Plugin API The GoodBarber plugin API is updated regularly, you can download the latest version from GoodBarber's GitHub profile (where you will also find examples of plugins).
1. How to use the GB JS ToolKit in your plugin Pour utiliser le GoodBarber JavaScript ToolKit dans votre plugin, téléchargez-en la dernière version en date sur le profil GitHub de GoodBarber. To use the GoodBarber JavaScript ToolKit in your plugin, download the latest version from GoodBarber's GitHub profile. Add the JavaScript file
"GBJSTK.js" to the file bundle of your plugin.
In the HTML code of the of the pages of the plugin that require it, add this line to the HEAD tag. <script language="JavaScript" src="./GBJSTK.js">
2. 3. 2. GBJS ToolKit Documentation This is a list of the parameters and methods available in the GoodBarber JavaScript ToolKit.
1. Var : int gbDebuggingMode Sets the debugging mode using a system of code values.
Values : - 0 : Production mode - 1 : Alerts before any request - 2 : Alerts before any request + stop requests
2. Function : gbIsEmpty This function tests if an object is empty.
Arguments : - obj : The action of the form
Return : - true : if the object is empty - false : otherwise
3. Function : gbConstructQueryString gbConstructQueryString This function constructs a query string using the "params" dictionary.
Arguments : - params : The params to construct the query string
Return : The constructed query string
4. Function : gbPostRequest This function creates a form in document.body and sends a POST request to "path" using "getParams" and "postParams".
Arguments : - path : The action of the form - params : The parameters to send in the request body
5. Function : gbGetRequest This function launches a navigation to "path" setting "params" as GET arguments.
Arguments : - path : The destination path - params : (optional) The params to send in the request body
6. Function : gbMailto Launches the mail composer. Arguments : - to : The destination address - subject : (optional) The mail subject - body : The (optional) mail content
7. Function : gbTel Launches a call. Arguments : - phoneNumber : The number to call
8. Function : gbSms Launches the SMS composer. Arguments : - phoneNumber : The number to send a text to
9. Function : gbMaps Launches the Maps native application.
Arguments : - params : The parameters to pass in the query string
10. Function : gbOpenApp Tests if the current device can handle the URL scheme ("scheme" param), if so opens it, or opens the url ("url" param) otherwise.
Arguments : - scheme : The URL scheme to test - url : The URL to launch otherwise
11. Function : gbGoToSection Goes to the section identified by its "id". Arguments : - id : The id of the destination section
12. Function : gbNavigatePush Launch a push navigation between two pages of the plugin.
Arguments : - page : The destination page - postParams : The postParams to give to the destination page
13. Function : gbNavigateModal gbNavigateModal Launch a modal navigation between two pages of the plugin. Arguments : - page : The destination page - postParams : The postParams to give to the destination page
14. Function : gbNavigateBack gbNavigateBack Launch a back navigation between two pages of the plugin.
15. Function : gbRequest Starts a request to the url resource, using the "method" method, and passing the "postParams" params if method==POST.
Arguments : - resourceUrl : The url of the resource to load - tag : A tag to identify the request - cache : YES if you want to use the app's cache mechanism, NO otherwise - requestMethod : The HTTP method you want to use for the request
- postParams : If method==POST, you can pass HTTP Post Params in your request Callbacks : - gbRequestDidFail ( tag, errorCode, errorMessage ) - gbRequestDidSuccessWithCache ( tag, data, src ) - gbRequestDidSuccess ( tag, data, src )
16. Function : gbAuthenticate Ask the user to authenticate on a social network.
Arguments : - services : The services to use for the authentication | values : [all(default)|facebook|twitter] - skip : Give the user the possibility to skip the authentication process | values : [YES(default)|NO] Callbacks : - gbDidSuccessAuthentication ( socialUser ) - gbDidFailAuthentication ( errorMessage )
17. Function : gbShare Ask the user to share a content on a social network. Arguments : - shareText : The text to share - shareLink : The link to share
18. Function : gbGetMedia Asks the user to take or choose a picture/movie. Arguments : - mediaType : The type of media that you want the user to take or choose | values : [photo(default)|video] - mediaSource : The source (camera or library) | values : [all(default)|camera|library] Callbacks : - gbDidSuccessGetMedia ( data, src ) - gbDidFailGetMedia ( errorMessage )
19. Function : gbGetLocation Asks for the users geolocation. Callbacks : - gbDidSuccessGetLocation ( lat, long ) - gbDidFailGetLocation ( errorMessage )
20. Function : gbGetTimezoneOffse gbGetTimezoneOffsett Asks for the time difference between UTC time and local time, in minutes.
Callbacks : - gbDidSuccessGetTimezoneOffset( offset )
2. 4. Examples & Tutorials 2. 4. 1. Tutorial : How to implement a basic Navigation If your plugin must display it's content over several pages (typically for a list of a content and a page from that list), you must delegate the navigation between these pages to the plugin in order to be able to benefit from native transitions. To do so, the Plugin API and the GoodBarber JavaScript ToolKit offer two different methods: - Push navigation (in depth) - Modal navigation (transversal) In this example, we're going to use the GoodBarber JavaScript ToolKit.
1. Objective In this example, we want to create a plugin with three pages: - The main page (index.html (index.html ) - A detail page (detail.html (detail.html ) - A modal page (modal.html (modal.html ) The main page (index.html) (index.html) will comprise two clickable zones triggering a navigation: one towards the detail page (in push navigation) and one to the modal page (in modal navigation). Each of the two targeted pages (detail.html (detail.html and modal.html ) will contain a zone that will trigger a return within the navigation hierarchy (back navigation).
2. 1. Creating the index.html page Nous allons commencer par créer la page index.html . Nous allons y créer les deux
correspondant aux zones cliquables, et y associer des actions (via l'attribut onClick) déclenchant respectivement les méthodes gbNavigatePush et et gbNavigateModal . We will create the two
corresponding to the two clickable zones, and associate further actions (via the attribute onClick) triggering the methods gbNavigatePush and gbNavigateModal , respectively. This is the content of the tag in the index.html file:
Home
Push Navigation
Modal Navigation
In both instances, the first argument of the method corresponds to the targeted page (without the extension), and the second to the data that may need to be transmitted to the destination page.
3. 2. Creating the detail.html and modal.html pages In these two pages, we will create a
that will correspond to a clickable zone allowing a return back within the navigation. This will done through a call to the method gbNavigateBack . This is the content of the tag in the detail.html file: file:
Detail
Back Navigation
This is the content of the tag in the modal.html file: file:
Modal
Back Navigation
4. 3. Result You can now easily test the navigation by downloading this sample plugin from GoodBarber's GitHub page, or by following the steps outlined in paragraphs 1 and 2.
2. 4. 2. Plugin Example : Weather by Geolocation In this example of a plugin, we will make a request to the API REST of the site Weather Underground to display the current weather conditions as a function of the user's geographic location. We will therefore attempt to search for the current location of the terminal (gbGetLocation method) and send the requests to the network (gbRequest method). This plugin is rather simple, it's purpose is to illustrate how to use the methods of the GoodBarber Plugin API. Please note: This plugin uses the GoodBarber JavaScript ToolKit.
1. Architecture of the plugin
Le plugin n'a pas vocation à implémenter une navigation car il se contente d'afficher 3 informations sur une seule page, on ne retrouve donc que la page index.html . This plugin won't implement a navigation as it is only intended to display three different types of information on one page, therefore, one will not find the page index.html. We have a CSS sheet (style.css ( style.css ), ), as well as several images for the plugin (in the following formats: .gif, .png, and .jpg). Finally, there are two JavaScript files: The GoodBarber JavaScript ToolKit (GBJSTK.js ( GBJSTK.js ) and the file of functions specific to the plugin (plugin.js (plugin.js ). ).
Please note: In order to ensure the optimal showing regardless of different screen types (particularly Retina and nonRetina screens) we have used media queries in the CSS sheet. By convention, the images in double size (for Retina screens) carry the suffix "@2x", just like with native developments.
2. How the plugin works
The operation of this plugin is relatively simple: Once it's instantiated, it will trigger it's refresh method, which will send a cascade request to obtain the geolocation of the user. If this request is successful, a request will be sent to the Weather Underground API. If the API works correctly, the page will be refreshed with the current information. Otherwise, the user will be informed that an error has occurred during the update process. A click on the refresh button will re-start the refresh process.
3. How can I test this plugin? In order to test this plugin in your GoodBarber app, download it from GoodBarber's GitHub profile, and then import it to a plugin section in your GoodBarber backend. You can then modify it in order to discover the possibilities provided by the GoodBarber Plugin API and the GoodBarber JavaScript ToolKit. You simply need to sign up (for free) on Weather Underground (http://www.wunderground.com/weather/api/) to get an API key, which you will then need to insert at the top of the file plugin.js.
3. Content API 3. 1. Content API Overview 3. 1. 1. Content API Overview The GoodBarber Content API allows you to access the content synchronized form the different sources that you have plugged in your sections. The Content API is built on a REST architecture. On each source, it's possible to call different methods, each meeting a specific need. The Content API requests are secured and can be called only from the app itself (or by a plugin in the app). To facilitate your tests, you can use an API Console in your backend. The auth management in the Content API is handled automatically by the request method method of the GoodBarber Plugin API.
1. General structure of Content API requests
The Content API calls URLs always follow this structure: http:// [myapp] / [section_id] / [arguments...] [myapp].goodbarber.com/apps/ [endpoint] [endpoint] / [section_id] / [arguments...] You can find the list of available sources for your app in your GoodBarber backend. The detailed list of endpoints is described in this article : Endpoints List.
2. General structure of Content API responses The responses of the Content API are always formatted as a JSON dictionary, and follow a general structure. The responses contain an array of items resulting of the request, and several other informations. The structure of the Content API responses is detailed in this article : Return structures & values.
3. Item type and inherited types The data returned by the Content API is always formatted as JSON dictionaries respecting the Item format. Each entry (article, video, tweet, photo, event, etc.) is an Item, having several additional keys specific to its type. The Item format specifications and the additional keys for each type are described in this article : Items types documentation.
3. 1. 2. Content API Use Policy 1. Authentication and use of the Content API The GoodBarber Content API calls are secure through a auth system, not documented. The GoodBarber Plugin API gives access to methods that encapsulate the authentication and make it transparent in calls. Only requests to a section belonging to the app itself can be authenticated. The GoodBarber Content API should be used only in Plugins developed for GoodBarber apps.
2. Content API modifications The requests and responses of the Content API can change anytime. It's important to follow the GoodBarber blog and this documentation.
3. 2. Content API Documentation 3. 2. 1. Endpoints List
The Content API endpoints allow you to access the content synced in your GoodBarber backend. Some sources allow only basic endpoints. To get the precise list of available endpoints for each source, have a look to the list of sources of your app.
1. /getLastItems The /getLastItems endpoint returns a list of items from the source plugged in the section "section_id "section_id ", ", in a reverse chronological order, and using the page and per_page parameters. Args : - section_id : the section id of the section connected to the source - page : page to call, calculated using per_page - per_page : number of items to return for this page Call structure : /getLastItems/ [section_id] / [page] / [per_page] / [section_id] / [page] / [per_page] /
2. /getPopularItems The /getPopularItems endpoint returns a list of items from the source plugged in the section "section_id "section_id ", ", in a popularity order, and using the page and per_page parameters. Args : - section_id : the section id of the section connected to the source - page : page to call, calculated using per_page - per_page : number of items to return for this page Call structure : /getPopularItems/ [section_id] / [page] / [per_page] / [section_id] / [page] / [per_page] /
3. /search The /search endpoint returns a list of items from the source plugged in the section "section_id "section_id ", ", filtered using the keyword arg, arg, and using the page and per_page parameters. Args : - section_id : the section id of the section connected to the source - keyword : keyword to search (has to be url encoded) - page : page to call, calculated using per_page - per_page : number of items to return for this page Call structure : /search/ [section_id] / [keyword] / [page] / [per_page] / [section_id] / [keyword] / [page] / [per_page] /
4. /getItem The /getItem endpoint returns the item having the id item_id on on the connected source of the section section_id . Args : - section_id : the section id of the section connected to the source - item_id : id of the item to return Call structure : /getItem/ [section_id] / [item_id] / [section_id] / [item_id] /
5. /getItemByUr / getItemByUrll The /getItemByUrl endpoint returns the item having the url item_url on on the connected source of the section section_id . Args : - section_id : the section id of the section connected to the source - item_url : URL of the item to return
Call structure : /getItemByUrl/ [section_id] / [item_url] / [section_id] / [item_url] /
6. /getCategories The /getCategories endpoint returns the list of categories of the connected source of the section section_id , using the page and and per_page parameters. parameters. Args : - section_id : the section id of the section connected to the source - page : page to call, calculated using per_page - per_page : number of items to return for this page Call structure : [per_page] / /getCategories/ [section_id] / [page] / [per_page] [section_id] / [page] /
7. /getItemsByCategorie /getItemsByCategorie The /getItemsByCategorie endpoint returns a list of items from the source plugged in the section "section_id "section_id ", ", filtered using the category_id arg, arg, and using the page and per_page parameters. Arguments : - section_id : the section id of the section connected to the source - category_id : id of the category - page : page to call, calculated using per_page - per_page : number of items to return for this page Call structure : /getItemsByCategorie/ [section_id] / [category_id] / [page] / [per_page] / [section_id] / [category_id] / [page] / [per_page] /
3. 2. 2. Return structure & values 1. Response of the Content API Each response of the Content API is designed to not generate more calls. The returned items are always full. Except for the Facebook and Soundcloud sources, which are very specific cases, the items returned for a call will always have the same type. The responses of the GoodBarber Content API are always done in JSON, and have always the same structure : { "generated_in" : "...", "items" : [...], "next_page" : "...", "stat" : "...", "title" : "...", "url" : "..." }
2. Keys Na Name generated_in items next_page
Type String Array of Items String
stat
String
title
String
Description Generation time of the response Array of items to be returned URL of the next_page to call (calculated with the page and and per_page args) Status of the response ("ok" is everything is fine, "error" otherwise) Title of the source
url
String
URL of the source
3. 2. 3. Item types documentation Each entry returned by the GoodBarber Content API is formatted on a generic Item dictionary type. The Item entries have common keys, and specific additional keys according to their type and and subtype . In the list below, for the specific types (articles, videos, etc.) inherited from Item, only the additional keys described.
1. Item (common) Generic Item type, every other type inherits from Item. Na Name id ty t yp e title url categories da t e author subtype
Type String String String String Array of Strings String (date) String String
Description Item unique identifier on its source Item type Item title Item URL on its source Categories associated with the item on the source Item publication date Item author Item subtype (generally describes the service type of the source)
2. Article Inherited from Item , can be displayed in Article sections. sections. = article type = = wordpress, typepad, wmaker, rss, etc. subtype = Na Name nbComments
Type Integer
commentsEnabled
Bool
commentsUrl
String
commentsPostUrl
String
summary
String
c co ontent smallThumbnail thumbnail largeThumbnail images images/[]/id
String String String String Array of Dict String
images/[]/url String Specifications to follow are described here : Articles sources.
Description Number of comments associated with the item on its source Describes if the comments have to be enabled or not for this item URL to access the JSON feed of comments for this item URL that allows to post comments on this item Summary of the article (no HTML, text only) Article content Article thumbnail (small format) Article thumbnail (medium format) Article thumbnail (big format) List of images contained in the article Value of the id attribute of the
tags in article content Image URL
3. Photo Inherited from Item , can be displayed in Photo sections. = photo type = = flickr, facebook, wmaker, picasa, etc. subtype = Na Name content nb n bLikes
Type String Integer
Description Photo description (text only, no HTML) Number of likes of the photo (only if
nbComments commentsEnabled
Integer Bool
commentsUrl
String
commentsPostUrl
String
images
Dict
images/{SIZE}/height images/{SIZE}/width images/{SIZE}/url Indicative values of {SIZE} Value square largesquare small medium large
Integer Integer String
subtype = facebook) Number of comments Describes if the comments have to be enabled or not for this item URL to access the JSON feed of comments for this item URL that allows to post comments on this item Dictionary of the different sizes available for the photo Height of the photo Width of the photo URL of the photo
Description Small format (square) Medium format (square) Small format (original proportions) Medium format (original proportions) Big format (original proportions)
Indicative values 75x75 150x150 240x180 320x240 640x480
4. Vidéo Inherited from Item , can be displayed in Video sections. = video type = = youtube, dailymotion, vimeo, wmaker, facebook, etc. subtype = Na Name nbComments commentsEnabled
Type Integer Bool
commentsUrl
String
commentsPostUrl
String
co c ontent summary
String String
smallThumbnail thumbnail largeThumbnail nbViews l e ng t h rating nbRatings videoUrls
String String String Integer Integer Float Integer Dict
videoUrls/{VIDEO_TYPE}
String
videoUrl
String
nb n bLikes
Integer
im i m ag e
String
Possible keys for {VIDEO_TYPE} Va Value m 3 u8 m p4 em embed
Description Number of comments Describes if the comments have to be enabled or not for this item URL to access the JSON feed of comments for this item URL that allows to post comments on this item Video description Summary of the video (no HTML, text only) Video thumbnail (Small format) Video thumbnail (Medium format) Video thumbnail (Big format) Number of views of the video Video duration (seconds) Medium rating of the video Number of ratings of the video Dictionary containing the different formats for the video source URL of the video resource corresponding to {VIDEO_TYPE} URL to watch the video (only if subtype = facebook) Number of likes of the video (only if subtype = facebook) Video original thumbnail URL (only if subtype = facebook)
Description URL of the HTTP Streaming feed URL of the MP4 file URL that could be indicated as the source of an HTML embed to watch the
Format Apple HTTP Streaming MP4 HTML embed
embedHTML
video HTML full embed code of the video
HTML embed
5. Event Inherited from Item , can be displayed in Event sections. = event type = = facebook, google, wmaker, etc. subtype = Na Name address al a llDay
Type String Bool
co c ontent endDate latitude
String String (date) String
longitude
String
thumbnail
String
Description Address of the event Describes if the event is an "all day" event Event description End date of the event Latitude of the event (GPS coordinates) Longitude of the event (GPS coordinates) Thumbnail of the event
6. Sound Inherited from Item , can be displayed in Sound sections. = sound type = = podcast, soundcloud, etc. subtype = Na Name nbComments commentsEnabled
Type Integer Bool
commentsUrl
String
commentsPostUrl
String
l e ng t h nb n bFavorites
Integer Integer
purchaseUrl streamUrl summary th t humbnail
String String String String
Description Number of comments Describes if the comments have to be enabled or not for this item URL to access the JSON feed of comments for this item URL that allows to post comments on this item Duration of the podcast (seconds) Number of "favorites" by user for this song (only if subtype = soundcloud) URL to buy the song Stream URL for this podcast Description of this podcast Thumbnail URL
7. Twitter Inherited from Item , can be displayed in Twitter sections. = twitter type = = twitter subtype = Na Name authorAccount s siince
Type String Integer
c co ontent thumbnail
String String
8. Facebook - Page Not-inherited type , used as header for Facebook sections. = facebook_page type = = facebook subtype =
Description Author's twitter account for this tweet Time spent since the publication of this tweet (seconds) Tweet content Tweet thumbnail URL (generally, author's profile picture)
Na Name au a uthor categories
Type String String
c co ontent cover founded
String String String
id nbLikes subtype thumbnail title type url ur urlScheme
String Integer String String String String String String
Description Page username Page category (has to be a Facebook category) Page description Cover picture URL Creation date as filled on the Facebook page settings Facebook profile identifier Number of likes on the Page In this case, always "facebook" Profile picture URL Name of the Facebook page In this case, always "facebook_page" Page URL Deep URL to access the Facebook page in the iOS Facebook app
9. Link Inherited from Item , can be displayed in Facebook sections (link items). = link type = = facebook, etc. subtype = Na Name nbComments nbLikes thumbnail c ca aption description link
Type Integer Integer String String String String
Description Number of comments Number of likes Thumbnail URL for this link Link caption Link description Link target (URL)
10. Status Inherited from Item , can be displayed in Facebook sections (status items). = status type = = facebook, etc. subtype = Na Name nbComments nbLikes co c ontent
Type Integer Integer String
Description Number of comments Number of likes Status content
11. Comment Inherited from Item , can be displayed in comment pages. = comment type = = wordpress, wmaker, etc. subtype = Na Name content
Type String
Description Content of the comment
12. Live Plus Inherited from Item , can be displayed in Live+ sections. = live type = = liveplus subtype = Na Name artist ti t itle
Type String String
Description Artist name Song's title
cover duration al a lbumTitle year
String Integer String Integer
URL of the song/album cover Song duration (seconds) Album title Année de parution de la chanson
3. 3. Items types specific rules 3. 3. 1. Article sources The Article sources (WordPress, TypePad, WMaker, RSS, etc.), that can be displayed in Article sections have several specificities in their Content API responses. In each case, an Article source should return only items having an "article" type, and the subtype can vary (ex: "wordpress", "typepad", "wmaker", etc.).
1. Specific management of images in article's content To allow the app to cache the images of the article, the images URLs mentioned in the article content have to appear in the array of dictionary images.
NB: The "id" attribute of the
tags contained in the article HTML code have to match the "id" key of a dictionary of the "images" array of the item.
2. Summary The summary attribute content will be displayed at the list level in the app.
3. Thumbnail management The article items return 3 thumbnails formats, that will be chosen by the app according to the active list template. Here are some indicative sizes: - smallThumbnail : 158x82 - thumbnail : 314x164 - largeThumbnail : original size of the image
3. 3. 2. Video sources The Video sources (YouTube, Dailymotion, Vimeo, WMaker, etc.), that can be displayed in Video sections have several specificities in their Content API responses. In each case, an Article source should return only items having an "video" type, and the subtype can vary (ex: "youtube", "dailymotion", "wmaker", etc.).
1. Specific management of the different video formats / embed The "content" key of the dictionary shouldn't contain the embed code of the video. Only its description (that can be formatted in HTML) has to be returned. The app inserts itself a button that allows the user to access the video in the detail page, using the values of the videoUrls dictionary. Here is the priority order of the dictionary entries: 1. embedHTML => If there is an embedHTML key, it's used in priority. Its content will be displayed without any modification 2. m3u8 / mp4 => If there isn't an embedHTML key, the app will show a button linking to the direct URL streams of the video 3. embed => If there isn't any direct stream URL for the video, the app will show an <iframe> having this key as source
2. Thumbnails management The video items return 3 thumbnails formats (in 16/9 ratio), that will be chosen by the app according to the active list template. Here are some indicative sizes: - smallThumbnail : 179x100
- thumbnail : 300x168 - largeThumbnail : original size of the image
3. 4. Build your own Custom Feeds 3. 4. 1. How to create your own Custom Feeds? You can create your own custom feeds, respecting the specifications of the Content API. Once these JSON content feeds created on your website, you'll be able to add them as sources of your sections, using the Custom connector. The values handled by the app are simple. Each element inherits from the Item type, and has some type specific attributes (like articles, videos, events, photos, ...). The values are described here : Item Types Documentation
You can download some examples here: Custom feeds examples
For each source type, it's possible to define several types of actions: - getLastItems => get the last items published, or items for a specific filter (like categories filters) - search => takes a [KEYWORD] argument to make a search in the website's content - getCommentsByItem => get the comments associated to an item
NB : The names getLastItems, search, getItemByCategorie, getCommentsByItem described in the documentation are the conventions that we use. When you add a custom source, you'll have to enter the whole URL to access your custom feeds, so it's not mandatory to respect this naming convention.
How to add a custom source in your sections