DeskPRO Apps Manual DeskPRO Apps Manual May 20th, 2014 • Revision #2 DeskPRO . . . . . . . . . . .Apps . . . . . . Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . . About . . . . . . .Apps ...........................................................................................................2 ................. Regular . . . . . . . . Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . Native . . . . . . .Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . Creating . . . . . . . . . .Widgets ........................................................................................................3 ................. Editing . . . . . . . . Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . . . . . . . . Javascript . . . . . . . . . . Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . . . . . . . HTML . . . . . . . Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . Example: . . . . . . . . . . .Link . . . . . .to . . CRM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 .................. Create . . . . . . .your . . . . . Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 ................. Widget . . . . . . . .Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 ................. Example: . . . . . . . . . . .Consuming . . . . . . . . . . . . . an . . . .API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 ................. Create . . . . . . .your . . . . . Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 ................. Widget . . . . . . . .Code: . . . . . . Javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 ................. Widget . . . . . . . .Code: . . . . . . HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 ................. Loading . . . . . . . . .Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 ................ Iterating . . . . . . . . .over . . . . . results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 ................ The . . . . full . . . . template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 ................ More . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 ................. Coding . . . . . . . . Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17 ................. Packaging . . . . . . . . . . . Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 ................. Native . . . . . . . Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 ................. DeskPRO Apps Manual 1 DeskPRO Apps Manual About Apps Apps are collections of HTML templates and Javascript controllers that change how DeskPRO looks and operates. Throughout the DeskPRO Agent Interface, there are dozens of predefined locations where you can inject your custom HTML templates (if these predefined locations don't suit you, there are also ways to fine-tune the insertion point). Using Javascript, you can add functionality to your HTML to create fully-functional "apps" that live directly within the DeskPRO interface and have access to the same data that DeskPRO has. All apps operate in roughly the same way, but there are three broad categories of apps: Regular Apps Apps are distributed as ZIP archives. To install an app, you upload it to your helpdesk from the Admin Interface. Most Apps are fairly simple and are just a few HTML and Javascript files. But they can get pretty advanced with multiple source files (e.g., modular Javascript code), external data files, images, and maybe even settings with an installer. We'll go over how to create and package apps later in this manual. Widgets Widgets are simple apps that you can create and manage completely from within the Admin Interface. These work in the same was a regular apps, except you edit HTML and Javascript files from the Admin Interface so you don't have to go through the trouble of packaging and distributing a ZIP file. Creating widgets is the simplest way to add simple features to your helpdesk right now with little learning curve. Native Apps Finally, for customers who run DeskPRO on their own server, you have the ability to create Native Apps. A native app is exactly the same as a regular app except you also have the ability to run native PHP code. There aren't many cases where you would need to use a Native App instead of a regular app. In the majority of cases, it's easier to consume a web service from an app (via Javscript/AJAX) instead of using native PHP code executed by DeskPRO. But if you really need it, the option is there. About Apps 2 DeskPRO Apps Manual Creating Widgets Creating and managing widgets is done entirely from the Admin Interface. Go to the Apps sections and then click the Create Widget button. You will see the New Widget form which is where you define the properties of your widget. To start with, give your widget a meaningful title that describes its purpose. The title is only used in the Admin Interface so it's mainly just a reminder to yourself. The next sections, Tickets, Users, and Organizations, let you define where you want to add your HTML and Javascript to. In the above screenshot, I've selected a single Ticket location, "A new tab in the properties box". This renders my HTML template into a new tab at the top of the Ticket view: Creating Widgets 3 DeskPRO Apps Manual You can select as many locations as you want to. Creating Widgets 4 DeskPRO Apps Manual Editing Widgets After you have created a widget, select it from the "Your Widgets" section of the Apps area in the Admin Interface. The first thing you see is this App Definition. It looks a little scary, but you can ignore this section entirely. It was automatically generated by DeskPRO and you will probably never need to edit it. The fact is that Widgets are actually fully-feautred Apps under-the-covers, and the App Definition is how an app configures itself. It tells DeskPRO which templates you have defined and where to put them. Ignore the first App Definition tab and switch to any of the other tabs which contain the HTML and Javascript templates you can edit to actually add content to your widget. For every location you checked during the widget creation step, you will have two files: A Javascript controller and an HTML template. Javascript Controller The Javascript file is what we call a controller. Here is where you can add custom Javascript code like AJAX calls or event handlers. All of your JS code should live within that one function controller. You'll notice that the default JS controller accepts a number of paramaters. The next section goes into more detail about how JS controllers work, but briefly: Editing Widgets 5 DeskPRO Apps Manual $scope is a special object that lets you connect your JS controller to your HTML template. Any value you assign to $scope will be available from your template. We'll go over a few examples in a moment. $ticket is an object containing all of the current ticket information including things like the ticket ID, the subject, the user, the user email etc. There is a lot of information here. To view the available values, the easiest thing to do is use console.log($ticket) and then view your browser console (e.g., Chrome Developer Console). If you specified a different tab type, such as a user or organization profile, you won't see $ticket . Instead you'll have $person or $org which are user info and org info, respectively. $person $http is also available on tickets, it's an alias for $ticket.person . is a service for performing AJAX requests. We'll go over a few examples below. $el contains a jQuery-wrapped element that is the outer container for your HTML template. You can use this to fine specific elements in your HTML template. For example, $el.find('input') to find an input box. Note that there are much better ways than using jQuery for connecting your JS controller to your template. The next section goes into more detail. $app is a reference to the Javascript object that represents your widget app. It includes things like your app ID. You probably will never need to use this. HTML Template Below the JS file is the HTML template file. This HTML template has special features attached to it that makes it easy to interact with the JS controller. We go into more detail in the next section, but here are a few examples. Binding variables Perhaps the most common thing you will want to do is to render values from your JS controller in your HTML template. For example, perhaps you have done an AJAX lookup and want to render the results. To do this, just assign values to the $scope variable in your controller: $scope.name = 'Christopher' Then within your HTML template, use the variable syntax: Hello, {{name}} You can even use variables to generate things like links: <a href="http://example.com/script?name={{name}}">Hello, {{name}}</a> Attaching click events You could use jQuery and the to do it. $el variable to manually attach events. But there is a much cleaner way First, define a function callback on your $scope : $scope.submitForm = function() { alert("Hello!"); } Editing Widgets 6 DeskPRO Apps Manual Then in your HTML template, use the special ng-click attribute on an element: <button ng-click="submitForm()">Submit</button> Conditionally showing an element Use the special expression: attribute on an element to conditionally show an element based on a Javascript ng-if <div ng-if="name">Hello, {{name}}</div> <div ng-if="!name">You have no name</div> Binding form controls Binding form values can be done with the special ng-model attribute. When the form input changes, the target variable will be set on your Javascript $scope variable. Enter your name: <input type="text" ng-model="name" /> <button ng-click="submitForm()">Submit</button // Javascript $scope.submitForm = function() { alert("Hello, " + $scope.name + "!"); } Iterating over a collection If you have an array of data in your Javascript controller: $scope.family = [ { name: "John", age: 38 }, { name: "Jane", age: 36 }, { name: "Jesse", age: 12 } ]; ... then you can iterate over those values in your template with ng-repeat : <ul> <li ng-repeat="p in family"> {{p.name}} is {{p.age}} </li> </ul> Using data from the ticket Use the $ticket object. Here are some commonly used values: $ticket.id Editing Widgets - The ticket ID 7 DeskPRO Apps Manual $ticket.id - The ticket ID $ticket.subject - The ticket subject $ticket.agent - Is an object containing information for the currently assigned agent: $ticket.agent.id - The agent ID $ticket.agent.display_name - The agent name $ticket.agent.primary_email.email - The agents primary email address $ticket.agent.picture_url_80 - The agents profile picture scaled to 80x80. Replace '80' with any of these standard sizes: 80, 64, 50, 45, 32, 22, 16 $ticket.agent_team.name - The name of the currently assigned team $ticket.department.name - The name of the assigned department $ticket.status - The current status $ticket.urgency - The current urgency $ticket.person - An object containing information about the user who opened the ticket: $ticket.person.id - The agent ID $ticket.person.display_name - The agent name $ticket.person.primary_email.email - The agents primary email address $ticket.person.picture_url_80 - The agents profile picture scaled to 80x80. Replace '80' with any of these standard sizes: 80, 64, 50, 45, 32, 22, 16 To use these values in your HTML template, you need to assign them to the $scope : // Javascript $scope.user_name = $ticket.person.display_name; // HTML Hello, {{user_name}} Or you could assign the entire ticket object to the scope: // Javascript $scope.ticket = $ticket; // HTML Subject: {{ticket.subject}}<br/> User Name: {{ticket.person.display_name}}<br/> User Email: <a href="mailto:{{ticket.person.primary_email.email}}">{{ticket.person.primary_email.email}}</a> Performing AJAX requests Use the $http service to perform AJAX requests. The Apps system is powered by a framework called AngularJS, and $http is a built-in service. You can refer to the official documentation for detailed API information: https://docs.angularjs.org/api/ng/service/$http Editing Widgets 8 DeskPRO Apps Manual Here's an example of using $http to perform an AJAX call to a web-service. After the result comes back, see how we assign the value to $scope which we use in the template: // Javascript $scope.is_loading = true; $http.get('/web-service').success(function(data) { $scope.is_loading = false; $scope.customer = data.customer; }); // HTML <div ng-if="is_loading">Loading results, please wait...</div> <div ng-if="!is_loading"> Customer ID: {{customer.id}} </div> Note that due to a browser security feature called same-origin policy , you cannot use AJAX to load web services from external domains. For example, if your helpdesk is on support.example.com you cannot use $http to perform AJAX requests against other-domain.com because the domain is different and the browser will reject the request. If your API supports JSONP, you can use that method instead via $http.jsonp . Otherwise, you can use the DeskPRO proxy service which allows you to proxy a AJAX requests through DeskPRO to make remote API calls: var params = { url: 'http://other-domain.com/api/some-service', email_address: $ticket.person.primary_email.email, other_params: 'example', something: 'these other params will be passed as-is to your remote service' }; $http.get('DP_URL/agent/misc/proxy', {params: params}).siccess(function(data) { // ... }); Note that the special DP_URL to the URL of your helpdesk. prefix in the URL will be automatically replaced Much more... There is much much more you can do with your Javascript and HTML templates that we will go over in the next section. Editing Widgets 9 DeskPRO Apps Manual Example: Link to CRM One of the simplest examples would be to create a widget that displays a link to an external system, such as a CRM. Most CRMs offer a way to look-up a user based on criteria like an email address. In this example, we use an app that outputs a link with the users email address in it. Create your Widget First, create your app from Admin > Apps > Create Widget like described in the previous section. Select where you want your link to appear. In this example, we'll create a new section under the properties box: Widget Code Switch to the Tickets tab to see the two inputs for our Javascript controller and HTML template. In this example, we'll be using the users email address to generate a simple HTML link. So in the first box we need to assign the email address variable to the $scope so it becomes available to the HTML template: Example: Link to CRM 10 DeskPRO Apps Manual define(function() { return function($scope, $ticket, $person, $http, $el, $app) { $scope.user_email = $person.primary_email.email; }; }); Then we are free to use the new user_email variable in our HTML template. Here's an example template. It has a bit of styling around the outer div to make it a bit prettier on the view-ticket screen. <div style="margin-top: 10px; padding: 5px; background: #fff; border: 1px solid #ccc; border-radius: 4px;"> <a href="http://example.com/crm/find-user?email={{user_email}}" target="_blank">Look up {{user_email}} in CRM </div> This is what it looks like when we view a ticket in the Agent Interface: Example: Link to CRM 11 DeskPRO Apps Manual Example: Consuming an API Another common use-case for widgets is to consume an API and display data directly in the Agent Interface. For example, maybe you run an online store and you want to show the users recent purchases. Create your Widget First step is to create your app like we've done before from Admin > Apps > Create Widget. In this example, we'll create a new tab in the properties box: Widget Code: Javascript Switch to the Tickets tab so we can edit the Javascript controller code. We can make AJAX requests with the $http service. Full documentation on the $http service can be found on the official AngularJS website: https://docs.angularjs.org/api/ng/service/$http Example: Consuming an API 12 DeskPRO Apps Manual Note that due to browser security features, you cannot make AJAX calls to services on a different domain from the current domain. To get around this limitation, DeskPRO has a special proxy script we can use that will pass-through a request to a remote service. Here's an example using DeskPRO proxy: $http to perform an AJAX request to a remote web service through the define(function() { return function($scope, $ticket, $person, $http, $el, $app) { // Setting a loading indicator like this means we // can show a loading message in our HTML template $scope.is_loading = true; var params = { url: "http://api.example.com/lookup-orders", // Any other parameters will be sent as-is // to your remote web service. // For example, here we are sending an 'email' parameter: email: $person.primary_email.email }; $http.get('DP_URL/agent/misc/proxy', {params: params}).success(function(data) { $scope.is_loading = false; $scope.orders = data.orders; }); }; }); For the sake of our example, let's pretend our web service returned the following data: [ { id: 1, title: "iPhone", total: 649.00 }, { id: 2, title: "Headphones", total: 32.99 }, { id: 4, title: "USB Cable", total: 3.99 }, { id: 5, title: "Phone Case", total: 24.99 }, ] In our controller we assigned those results to the scope with this line: $scope.orders = data.orders; Next we'll see how to show those results in our template. Example: Consuming an API 13 DeskPRO Apps Manual Widget Code: HTML We have two goals with this HTML template; 1 2 We want to show a loading message while the results are loaded. This means we need some kind of if/else logic in our template based on the is_loading variable we set in our Javascript controller. We want to show a list of orders from our orders kind of looping feature to loop through the results. array. This means we need some Loading Indicator To show content based on a value, we can use a special HTML attribute ng-if : <div ng-if="is_loading">Loading results, please wait...</div> <div ng-if="!is_loading">Results are in!</div> The value of ng-if can be any Javascript expression. In this case, we are just taking the value of our is_loading varaible. But we could use any valid expression. For example: <div ng-if="1 + 1 == 2">Yes, 1+1 does equal 2</div> Iterating over results The next thing we want to do is iterate over the orders array so we can list the results we got from our web service. We can do this with another special HTML attribute called ng-repeat : <ul> <li ng-repeat="order in orders"> <a href="http://example.com/admin/order?id={{order.id}}"> {{order.title}} - ${{order.total}} </a> </li> </ul> ng-repeat syntax is <local variable> in <collection> and repeats the HTML element for each item in the collection. In our example, we repeated a <li> for each order in our orders array. The full template Putting it all together, our template looks something like this: Example: Consuming an API 14 DeskPRO Apps Manual <div ng-if="is_loading">Loading results, please wait...</div> <div ng-if="!is_loading"> <div ng-if="orders.length == 0"> This user has no orders. </div> <div ng-if="orders.length > 0"> <ul style="margin: 10px"> <li ng-repeat="order in orders"> <a href="http://example.com/admin/order?id={{order.id}}"> {{order.title}} - ${{order.total}} </a> </li> </ul> </div> </div> And here's what it looks like in the Agent Interface: Example: Consuming an API 15 DeskPRO Apps Manual More Examples See the DeskPRO Apps GitHub repository at https://github.com/DeskPRO/DeskPRO-Apps for more apps. More Examples 16 DeskPRO Apps Manual Coding Apps Coming Soon Coding Apps 17 DeskPRO Apps Manual Packaging Apps Coming Soon Packaging Apps 18 DeskPRO Apps Manual Native Apps Coming Soon Native Apps 19
© Copyright 2024