3 Replies Latest reply on May 20, 2013 12:13 PM by elainecc

    cryptic points in the API

    AMULI Level 4

      Diving into Edge and jQuery with a Flash and AS3 background, I would like to give feedback about difficulties I encounter studying the Edge API, believing the answers will benefit to others.

       

      1) Edge Animate Triggers, Events and Actions

       

      • A few properties of an event object are mentionned : e.target, e.originalEvent, e.compId. Why not listing them exhaustively (or a least giving a link to the API of such an event object) ?

       

      It took me a certain time to find on the web how to express what in AS3 comes down to <eventObject>.target.name to

       

      var elem, evt = e ? e : event;

      if (evt.srcElement)  elem = evt.srcElement;

      else if (evt.target) elem = evt.target;

      return elem.getAttribute("ID").substr(18,4);

       

      (not being sure there is nothing simpler)

       

      • Different categories of events are mentionned, among which composition-level DOM events and page-level DOM events. It would be greatly helpful if the two levels where clarified, with the relations between the two (or again a link to a page clarifying this).

       

      • Timeline events : update, play, complete, stop. This single list is rather lean ! I already started a thread (http://forums.adobe.com/message/5246740#5246740) to get more information, but in vain. If play, complete and stop may be considered self-explanatory, update is not clear : which rate is it fired ?

       

      • “compositionReady fires after the composition is ready to play, but before autoPlay occurs.“

      This is the only place where this event (it is an event ?) is mentionned.

       

      • A few sentences are cryptic to me (surely being not enough jQuery/JavaScript savvy) :

       

      - “he sym variable is more durable when you use things like setTimeout.“

       

      - “You can compare this to the  comId  passed to the actions function closure.“

       

      - “Other mouse events will be simulated if the click event is bound.“

       

      2) Work with symbols

       

      • “The child elements of a symbol instance are owned by that symbol and are referred to as Actors.“

      This is the only place where the term “Actor“ is mentionned.

       

      • It could be emphasized that there is a <CompositionObject>createSymbolChild() method, not to be confused with the <SymbolObject>.createChildSymbol (!!!), the latter having an additional z_index parameter.

       

      // Hide the element "paw" from within a nested symbol

      sym.getComposition().getStage().sym.getSymbol("kitten_1").getSymbol("kitten_paw").$("paw") .hide();

       

      It looks like the second occurrence of sym is one to many !?

       

      • Finally, to make matters worse, the french translation of this page is rough, even broken.

       

      “a child symbol instance of "kittenpaw_sym" inside the element "kitten""

       

      should be translated by : instance du symbole “kittenpaw_sym“, enfant de l’élément "kitten".

       

      and not : instance de symbole enfant de "kittenpaw_sym" dans l’élément "kitten".

       

      that has a different meaning and is very confusing. On several occasions, I tried to get in touch with the Adobe ––even Macromedia— French team about poor translations of the docs, but in vain ; is there a way to help improving, which would benefit the french-speaking community ?

       

      Gil

        • 1. Re: cryptic points in the API
          elainecc Adobe Employee

          Hi, Gil-

           

          Okay, there's a lot in this post.  Let's start with the last one first: we are definitely open to suggestions for the translations of the documentation.  If you have a laundry list of these things, I can file them with our linguists and have them fix it.  That being said, please remember that I am one human with a lot of Animate to work on, so the speed on these things might be kind of slow.

           

          Otherwise, we're constantly refining and rewriting our documentation.  Please do point these things out to us, because we write our documentation (and blog posts, and give talks about how to use Animate, and answer user requests).  I'll look at these issues you pointed out and see if I can get them fixed soon.

           

          I'll answer your frequency problem in the other post.

           

          Other miscellaneous points you brought up:

          • compositionReady is available by clicking on the {} button next to Stage in the Elements Panel (or by clicking on the + next to Stage in the code panel)
          • "durable" is probably not the right word, but the gist of the phrase is that when you use JavaScript functions like setTimeout, "sym" will point to the correct object, while "this" is not guaranteed to point to the right object, as the scope changes within the function.
          • actions closure - any event handler is called an "action" (hence the "actions pop up"), so the closure has to do with what lies within the function() call of the event handler
          • mouse events - basically, since there isn't a mouse on a touch-based device, the only event that is guaranteed to work is "click."  Sometimes the device will fake the other mouse events (like a touch for a mouseover), and sometimes they won't.

           

          -Elaine

          • 2. Re: cryptic points in the API
            AMULI Level 4

            Hi Elaine,

            we are definitely open to suggestions for the translations of the documentation.  If you have a laundry list of these things, I can file them with our linguists and have them fix it.

            Ok, I will when having explored completely. A thread is perhaps not the right place for that ? And I also have imagined that people at Adobe France are responsible for the french version.

            please remember that I am one human with a lot of Animate to work on, so the speed on these things might be kind of slow

            I just can imagine the pressure that is yours. So thank you again for taking time to responding and hang in there

            • compositionReady is available by clicking on the {} button next to Stage in the Elements Panel (or by clicking on the + next to Stage in the code panel)

             

            I did not express myself properly : I was just noticing this single mention of the autoplay event (and wondering if it is an event).

            • "durable" is probably not the right word, but the gist of the phrase is that when you use JavaScript functions like setTimeout, "sym" will point to the correct object, while "this" is not guaranteed to point to the right object, as the scope changes within the function.
            • actions closure - any event handler is called an "action" (hence the "actions pop up"), so the closure has to do with what lies within the function() call of the event handler
            • mouse events - basically, since there isn't a mouse on a touch-based device, the only event that is guaranteed to work is "click."  Sometimes the device will fake the other mouse events (like a touch for a mouseover), and sometimes they won't.

             

            Thank you again. This is perfectly clear !

             

            Otherwise, we're constantly refining and rewriting our documentation.

             

            Globally, I find Edge environment very attractive despite some "youthful mistakes".

             

            But to a certain point, when wanting to get a deeper understanding, there is a gap between the user-friendly approach and the developper world. And as often here, technicians use their lingo (A closure ? What's that ?), forgetting to define the concepts they use. If I have problems understanding, as a JavaScript noob, but a computer scientist, what for the webdesigner without such a background ?

             

            I wish Edge to be the same kind of junction between graphic design and coding as Flash is, without requiring to be a certified JavaScript expert (or making it easier to become one ?). I would be glad if I could help  refining the doc to help people mastering quicker as I did.

             

            Gil

            • 3. Re: cryptic points in the API
              elainecc Adobe Employee

              Hi, Gil-

               

              Sorry for not getting back to you sooner - chest cold knocked me flat for two weeks.

               

               

              Ok, I will when having explored completely. A thread is perhaps not the right place for that ? And I also have imagined that people at Adobe France are responsible for the french version.

               

               

              You can stick it in a thread or in a personal message using Jive.  I get both via Email, so I'll be able to track it internally. 

               

               

              I did not express myself properly : I was just noticing this single mention of the autoplay event (and wondering if it is an event).

              Autoplay is not an event - it's a setting that you can hit in the properties panel.  The autoplay setting controls whether or not a symbol (including the Stage) plays automatically when it is loaded.

               

               


              But to a certain point, when wanting to get a deeper understanding, there is a gap between the user-friendly approach and the developper world. And as often here, technicians use their lingo (A closure ? What's that ?), forgetting to define the concepts they use. If I have problems understanding, as a JavaScript noob, but a computer scientist, what for the webdesigner without such a background ?

               

              I wish Edge to be the same kind of junction between graphic design and coding as Flash is, without requiring to be a certified JavaScript expert (or making it easier to become one ?). I would be glad if I could help  refining the doc to help people mastering quicker as I did.

               

              Definitely help us out by pointing things that could be clearer in the documentation!  It's easy for us to change, and we want to make sure our users can understand the API.

               

              Thanks,

               

              -Elaine