Updated Branches: refs/heads/master 2238e2bbc -> 79419d437
[GSOC] Shiva Teja report Signed-off-by: Sebastien Goasguen <run...@gmail.com> Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/79419d43 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/79419d43 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/79419d43 Branch: refs/heads/master Commit: 79419d43736d49a86c2f7595bc8c62ddc1f9931f Parents: 2238e2b Author: Shiva Teja <shivate...@gmail.com> Authored: Mon Jul 29 12:21:17 2013 -0400 Committer: Sebastien Goasguen <run...@gmail.com> Committed: Mon Jul 29 12:21:17 2013 -0400 ---------------------------------------------------------------------- docs/en-US/gsoc-midsummer-shiva.xml | 257 ++++++++++++++++++- docs/en-US/images/add-account-screen.png | Bin 0 -> 71491 bytes docs/en-US/images/async-calls.png | Bin 0 -> 126157 bytes .../en-US/images/configuration-edit-success.png | Bin 0 -> 86909 bytes docs/en-US/images/configurations-screen.png | Bin 0 -> 85285 bytes docs/en-US/images/create-account-post.png | Bin 0 -> 116063 bytes docs/en-US/images/create-account-request.png | Bin 0 -> 169834 bytes docs/en-US/images/edit-configuration.png | Bin 0 -> 86589 bytes docs/en-US/images/instances-screen.png | Bin 0 -> 66865 bytes docs/en-US/images/list-domain-vms.png | Bin 0 -> 130442 bytes docs/en-US/images/list-specific-vm.png | Bin 0 -> 86323 bytes docs/en-US/images/list-virtualmachines.png | Bin 0 -> 124665 bytes docs/en-US/images/start-vm-screen.png | Bin 0 -> 65228 bytes docs/en-US/images/vm-running.png | Bin 0 -> 67708 bytes 14 files changed, 256 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/gsoc-midsummer-shiva.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/gsoc-midsummer-shiva.xml b/docs/en-US/gsoc-midsummer-shiva.xml index 67755c4..c26c5a8 100644 --- a/docs/en-US/gsoc-midsummer-shiva.xml +++ b/docs/en-US/gsoc-midsummer-shiva.xml @@ -24,5 +24,260 @@ <section id="gsoc-midsummer-shiva"> <title>Mid-Summer Progress Updates</title> - <para>This section describes ...</para> + <para>This section describes Mid-Summer Progress of Shiva Teja - "Create A New Modular UI for Apache CloudStack"</para> + <section id="introduction-shiva"> + <title>Introduction</title> + <para> + The progress on my project has been very smooth so far and I got to learn a lot. I started with learning git and backbone.js and then went on to learn angular.js and evantually made a basic usable UI with angular.js. Sebastien has been guiding me and helping me throughout the period. Both CloudStack and Angular.js communities have been helpful along the way. + </para> + <para>I am happy with the progress so far and it is possible to reach the goals with a slightly faster pace.</para> + </section> + <section id="ui-progress"> + <title>Progress and Experience So Far</title> + <para> + I made a basic UI from which a user can list a bunch of collections, launch VMs(and similar actions), edit configurations, add accounts, search through some of the fields. I've also added a very basic notification service and work is in progress for making a dropdown notification similar to the current UI. + </para> + <para> + I started by learning backbone.js and improving the prototype that I've made with my proposal. Then I looked into the current UI's code and tried to make plugins. There was a lot of repeated DOM manipulation and ajax calls throughout the UI.Then I almost took a week looking into angular.js and experimenting with it. I finally chose angular.js because it does lot more than backbone and lets you do the same stuff in lesser and more elegant code, thus, easily maintainable. It was obvious that most of repetitive DOM manipulation can be removed with angular's directives and AJAX calls with, obviously, models. This is one of important reasons I feel that CloudStack should move from just jQuery to an MVC like angular. Apart from code reusabilty for custom UIs, angular offers much lesser, more structured and elegant code. Rolling out new features becomes a much easier task. Implementing features like Quick View or UI tooltips that are present in the current UI is just a matter o f implementing another directive. + </para> + <para> + Learning the framework and developing the app while following best practices was not easy at the beginning. I had difficulties in deciding things like structure of the app. Looking into existing apps like <ulink url="https://github.com/angular-app/angular-app";><citetitle>angular-app</citetitle></ulink> and famous threads on the mailing list helped. + </para> + <para> + Another slightly challenging task was to desing the angular.js models for cloudstack. Angular.js documentation say just use any Plain Old Javascript Objects. Given that statement, there are so many possible ways of doing it. So deciding the best one was frustrating at the beginning, but turned out to be simple. A rule of thumb that I think should be followed throughout the app is to return <ulink url="http://docs.angularjs.org/api/ng.$q";><citetitle>promises</citetitle></ulink> whenever possible. Promises remove unnecessary callbacks and offers a much more elegant structuring of code. All the models and collections in the current UI return promises which allows us to take actions after the specified actions on models and collections takes place. + </para> + <para> + Making complex directives can also be frustrating at the beginning. Videos from <ulink url="http://egghead.io";><citetitle>egghead.io</citetitle></ulink> came handy for understanding directives in depth. I feel that these are the next most powerful things that angular offers after 'the ability to use POJOs for models'. All the DOM manipulations can be put into directives and can be reused easily. + </para> + </section> + <section id="ui-screenshots"> + <title>Screenshots</title> + <para>I'll try to explain the things that you can do with the UI developed so far with some screenshots and a bit of the code assosciated</para> + <section id="instances-tab"> + <title>Instances tab</title> + <itemizedlist> + <listitem> + <mediaobject> + <imageobject> + <imagedata fileref="./images/instances-screen.png"/> + </imageobject> + <textobject> + <phrase>instances-screen.png: Instances tab</phrase> + </textobject> + </mediaobject> + </listitem> + <listitem> + <para>Simple confirmation modal when you click start vm button</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/start-vm-screen.png"/> + </imageobject> + <textobject> + <phrase>start-vm-screen.png: Start vm screen</phrase> + </textobject> + </mediaobject> + <para>This is simple directive which launches such modal on click and can perform actions for 'yes' and 'no' clicks.(can be found at static/js/common/directives/confirm.js). In this case it'll call model.start() which will call the requester service to start the vm</para> + </listitem> + <listitem> + <para>And the vm is running!</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/vm-running.png"/> + </imageobject> + <textobject> + <phrase>vm-running.png: Running vm</phrase> + </textobject> + </mediaobject> + <para>Labels automatically get updated by watching model changes</para> + </listitem> + <listitem> + <para>Async calls</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/async-calls.png"/> + </imageobject> + <textobject> + <phrase>async-calls.png: Example Async Calls</phrase> + </textobject> + </mediaobject> + <para>Async calls are taken care by a service named requester which returns a promise. It resolves the promise when the query-async-job request returns with a result</para> + </listitem> + </itemizedlist> + </section> + <section id="modal-forms"> + <title>Example Modal Forms</title> + <itemizedlist> + <listitem> + <para>The Modal Form for adding an account</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/add-account-screen.png"/> + </imageobject> + <textobject> + <phrase>add-account-screen.png: Add Account</phrase> + </textobject> + </mediaobject> + <para>modal-form is directive that I wrote which can used for modal forms across the UI. Example usage can be seen in accounts or volumes in static/js/app</para> + </listitem> + <listitem> + <para>Create Account request sent on submitting that form</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/create-account-request.png"/> + </imageobject> + <textobject> + <phrase>create-account-request.png: Create Account Request</phrase> + </textobject> + </mediaobject> + </listitem> + </itemizedlist> + </section> + <section id="edit-configurations"> + <title>Edit Configurations</title> + <itemizedlist> + <listitem> + <mediaobject> + <imageobject> + <imagedata fileref="./images/configurations-screen.png"/> + </imageobject> + <textobject> + <phrase>configurations-screen.png: Configuration Screen</phrase> + </textobject> + </mediaobject> + <para>I've moved the description of the configurations from a column in the current UI to a tooltip. These tooltips appear when you hover over the configurations.</para> + </listitem> + <listitem> + <para>An input text box like this appears when you click edit</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/edit-configuration.png"/> + </imageobject> + <textobject> + <phrase>edit-configuration.png: Configurations edit screen</phrase> + </textobject> + </mediaobject> + <para>This is handled by edit-in-place directive that I wrote</para> + </listitem> + <listitem> + <para>This shows that the configuration has been updated and the basic notification service that pops up</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/configuration-edit-success.png"/> + </imageobject> + <textobject> + <phrase>configuration-edit-success.png: Configurations edit success screen</phrase> + </textobject> + </mediaobject> + <para>It is as simple as calling model.update when the save button is clicked. As it returns a promise, it can be used to call the notification service whenever there are model changes.</para> + </listitem> + </itemizedlist> + <para>I tried my best to give an overview on code along with the screenshots. For more on the <ulink url="https://github.com/shivateja/cloudstack-ui/tree/angular-rawapi";><citetitle>code</citetitle></ulink>, I'd recommend going through it thoroughly, as I'd love to have someone look at my code point out mistakes at this early stage.</para> + </section> + </section> + <section id="rest-api"> + <title>RESTful API</title> + <para>I worked on the RESTful API for a while. I read a lot about REST but I could not get an elegant way of designing the API for the non RESTful verbs like start, stop etc. I have finished working the on the verbs that are RESTful(like list, update, delete..etc). The API can also handle sub-entities like listing virtual machines in a domain</para> + <para>Here are some screenshots:</para> + <itemizedlist> + <listitem> + <para>List all virtual machines. Anything similar should work</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/list-virtualmachines.png"/> + </imageobject> + <textobject> + <phrase>list-virtualmachines.png: List All Virtual Machines</phrase> + </textobject> + </mediaobject> + </listitem> + <listitem> + <para>List the properties of a specific vm</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/list-specific-vm.png"/> + </imageobject> + <textobject> + <phrase>list-specific-vm.png: List Properties of a specific vm</phrase> + </textobject> + </mediaobject> + </listitem> + <listitem> + <para>List virtual machines of a domain. Anything similar should work</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/list-domain-vms.png"/> + </imageobject> + <textobject> + <phrase>list-domain-vms.png: List virtual machines of a domain</phrase> + </textobject> + </mediaobject> + </listitem> + <listitem> + <para>Create an account with a POST request. You can also do update, delete etc.</para> + <mediaobject> + <imageobject> + <imagedata fileref="./images/create-account-post.png"/> + </imageobject> + <textobject> + <phrase>create-account-post.png: Create Account with POST request</phrase> + </textobject> + </mediaobject> + </listitem> + </itemizedlist> + </section> + <section id="misc-shiva"> + <title>Miscellaneous</title> + <para>There are lot of other things that I've experimented with along the way which are not shown in screenshots. Although my initial timeline was designed keeping backbone.js in mind, I've been following a similar version of it till now. It has been a bit slow as I had to learn and implement at the same time. I've been rolling out things very fast for the past couple of weeks as I am good to go with most of the angular.js concepts. The project can be finished very easily if I continue the same pace. Here's a list of important things that will be implemented next, in the same order(I have already experimented with most of them.)</para> + <itemizedlist> + <listitem> + <para>Authentication handling: This is a slightly tough task. I looked into existing apps and made a basic security service which can be used for this purpose.</para> + </listitem> + <listitem> + <para>Infinite scroll directive: I am loading all the data at a time in the current UI. This does not work well with huge production clouds. Again, changes the structure of collections slightly, important thing to be taken care of before doing further development.</para> + </listitem> + <listitem> + <para>A modal wizard directive required for adding instances.</para> + </listitem> + <listitem> + <para>After finishing those three I'd be equipped with enough UI stuff that can let me concentrate on my models. I'll try to add as many functionalities to the models which can easily used throught this UI, and also reusable in custon UIs. After finishing these, I'll implement a better notification system.</para> + </listitem> + <listitem> + <para>Tests: Although I should've done these parallelly while developing the UI, given the lack of experience, it took me some time to realize that tests are important. I have setup a test environment karma and I'll soon write tests for whatever I've written so far.</para> + </listitem> + </itemizedlist> + </section> + <section id="experience-shiva"> + <title>Experience gained working on OSS and CloudStack</title> + <para>Working on OSS has been very different and offered much more to learn what a university project could offer me. Asking and answering questions is one of the important thing that really helped me and I feel this was the important part of the development so far. Although I was a bit shy to ask questions at the beginning, I really loved the way angular.js community has helped even for silly questions. Soon, I realized the same happens on the CloudStack mailing list or any OSS mailing list for that matter. Solving others problems also helps a lot in building up knowledge. So, answering questions is also one of the important thing about working on Open Source Software. Being nice and polite on the public discussions like this improves personality. I am really glad to be a part of it now and very thankful to Google for such a wonderful program that introduces students to real-world software problems at very early stages of student's experience.</para> + <para>I did not know much about CloudStack itself when I started working on the project. Following the discussions on mailing list, I googled for different terms used, watched a few videos on cloud and I'm really interested in learning more. I really hope to join the real CloudStack development soon.</para> + </section> + <section id="conclusion-shiva"> + <title>Conclusion</title> + <para>You can find a demo of the UI <ulink url="http://students.iitmandi.ac.in:20000";><citetitle>here</citetitle></ulink> live in action.</para> + <para>I am really happy with the progress and experience so far. The goals of the project look easily reachable with the experience I have now. I still have RESTful API to be handled at the end. So I'll have to finish most of the project by the end of the august. Each of the task in the next todo list I've mentioned above should not take much time if things go well and models required for the UI should be ready by august last week so that I can take care of any UI specific things and RESTful stuff. + </para> + <para>Here's small list of things that I've learned so far:</para> + <itemizedlist> + <listitem> + <para>Git concepts, along with using JIRA and Review Board.</para> + </listitem> + <listitem> + <para>Some advanced JS concepts and JS frameworks like jQuery, backbone.js, angular.js. Using Twitter Bootstrap for faster UI development.</para> + </listitem> + <listitem> + <para>Basics of designing and structuring RESTful APIs</para> + </listitem> + <listitem> + <para>Cloudmonkey's code and usage. I had to look into its code when I was designing the RESTful API.</para> + </listitem> + <listitem> + <para>A bit more in depth understanding of Flask web framework</para> + </listitem> + <listitem> + <para>Exposure to testing environment like karma and testing the UI in different browsers</para> + </listitem> + </itemizedlist> + <para>Code written so far is available <ulink url="http://github.com/shivateja/cloudstack-ui/tree/angular-rawapi";><citetitle>here</citetitle></ulink> and <ulink url="http://github.com/shivateja/cloudstack-restful-api";><citetitle>here</citetitle></ulink></para> + <para>I thank Google and CloudStack for giving me this oppurtunity, Sebastien and Kelcey for helping me along the way.</para> + </section> </section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/add-account-screen.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/add-account-screen.png b/docs/en-US/images/add-account-screen.png new file mode 100644 index 0000000..aaa798f Binary files /dev/null and b/docs/en-US/images/add-account-screen.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/async-calls.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/async-calls.png b/docs/en-US/images/async-calls.png new file mode 100644 index 0000000..e24eee7 Binary files /dev/null and b/docs/en-US/images/async-calls.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/configuration-edit-success.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/configuration-edit-success.png b/docs/en-US/images/configuration-edit-success.png new file mode 100644 index 0000000..2e21dc1 Binary files /dev/null and b/docs/en-US/images/configuration-edit-success.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/configurations-screen.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/configurations-screen.png b/docs/en-US/images/configurations-screen.png new file mode 100644 index 0000000..5458608 Binary files /dev/null and b/docs/en-US/images/configurations-screen.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/create-account-post.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/create-account-post.png b/docs/en-US/images/create-account-post.png new file mode 100644 index 0000000..ea5ce3f Binary files /dev/null and b/docs/en-US/images/create-account-post.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/create-account-request.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/create-account-request.png b/docs/en-US/images/create-account-request.png new file mode 100644 index 0000000..b36d1ff Binary files /dev/null and b/docs/en-US/images/create-account-request.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/edit-configuration.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/edit-configuration.png b/docs/en-US/images/edit-configuration.png new file mode 100644 index 0000000..43874bf Binary files /dev/null and b/docs/en-US/images/edit-configuration.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/instances-screen.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/instances-screen.png b/docs/en-US/images/instances-screen.png new file mode 100644 index 0000000..74a1f08 Binary files /dev/null and b/docs/en-US/images/instances-screen.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/list-domain-vms.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/list-domain-vms.png b/docs/en-US/images/list-domain-vms.png new file mode 100644 index 0000000..1717f55 Binary files /dev/null and b/docs/en-US/images/list-domain-vms.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/list-specific-vm.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/list-specific-vm.png b/docs/en-US/images/list-specific-vm.png new file mode 100644 index 0000000..4fa1da4 Binary files /dev/null and b/docs/en-US/images/list-specific-vm.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/list-virtualmachines.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/list-virtualmachines.png b/docs/en-US/images/list-virtualmachines.png new file mode 100644 index 0000000..cd9401e Binary files /dev/null and b/docs/en-US/images/list-virtualmachines.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/start-vm-screen.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/start-vm-screen.png b/docs/en-US/images/start-vm-screen.png new file mode 100644 index 0000000..75a604a Binary files /dev/null and b/docs/en-US/images/start-vm-screen.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/79419d43/docs/en-US/images/vm-running.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/vm-running.png b/docs/en-US/images/vm-running.png new file mode 100644 index 0000000..e50cd16 Binary files /dev/null and b/docs/en-US/images/vm-running.png differ
