Moodle
  1. Moodle
  2. MDL-45885

Decide and document output components

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Deferred
    • Affects Version/s: 2.8
    • Fix Version/s: FRONTEND
    • Component/s: Libraries
    • Labels:
    • Story Points (Obsolete):
      40
    • Sprint:
      FRONTEND Sprint 13

      Description

      This is an essential part of the task - unfortunately the approaches are broad and what we choose now we have to commit to and live with.
      It has to meet our needs now and in the future.

      Some of the things that need to factor into this decisions are:

      Element and component re-use
      Re-use is key to this approach. We want to have components containing existing elements and components, and when we want to change how an element looks we want that change reflected in all uses of the element within other components that don't require it to look different.
      This way you can style a button and instantly have the look updated across other components like search forms containing buttons.

      Elements and components can be complex
      Elements don't need to be easy to write - they should be feature full and limited in number. Developers should not write components instead they should be re-using the available elements and components.

      Overriding a render to change how an element must be both easy and robust
      Re-use is key as per the above point.
      However we need to achieve this in such a way that we don't introduce magic and keep things simple to understand and override.
      We have to be able to deal with state and attribute requirements of the element in relation to its parent component and do it in such as way that the state is owned by the component and attributes are owner by the render method. and keep it all understandable.

        Gliffy Diagrams

          Activity

          Hide
          Sam Hemelryk added a comment -

          First up I'd like to share my thoughts on the two initial prototypes:

          Prototype A
          This prototype takes a very heavy, complex Object Orientated approach to this.
          It introduces a render method chain whereby several methods can take control of the rendering of a component|element in relation to its use within a component.
          The methods in the chain don't need to be implemented within the core renderer but can be introduced and utilised in the theme overriding renderer.
          This allows an theme renderer to completely alter how a components bits are rendered without need to override the component.
          It is very flexible in how controls rendering of bits, and how it manages bit state in relation to the component.
          It implements the perceived rules within code so that little is left to chance and developer interpretation.

          Prototype B
          This prototype takes the complete opposite approach.
          It is very similar to how we do things already with a little bit of re-use smushed into it.
          It has objects for components only and not for elements and in doing so reduces the need to understand the delivered structure.
          The downside is that re-use is simple and DOM manipulation for attribute handling is required.
          It is much easier to pick up and use, rather than implementing rules in code as prototype A has it will let the developer do as they wish and rules will have to be observed.

          So how I feel about them:

          Prototype A is complex. You would need to have a proper understanding of how it works before trying to utilise this functionality. Documentation would aid this - but really it is too complex.
          Prototype B I personally don't feel the re-use goes far enough and I lack to imagine how it could go further with the current handling of attributes and the lack of state handling without getting truly complex and perhaps a hacky.

          Show
          Sam Hemelryk added a comment - First up I'd like to share my thoughts on the two initial prototypes: Prototype A This prototype takes a very heavy, complex Object Orientated approach to this. It introduces a render method chain whereby several methods can take control of the rendering of a component|element in relation to its use within a component. The methods in the chain don't need to be implemented within the core renderer but can be introduced and utilised in the theme overriding renderer. This allows an theme renderer to completely alter how a components bits are rendered without need to override the component. It is very flexible in how controls rendering of bits, and how it manages bit state in relation to the component. It implements the perceived rules within code so that little is left to chance and developer interpretation. Prototype B This prototype takes the complete opposite approach. It is very similar to how we do things already with a little bit of re-use smushed into it. It has objects for components only and not for elements and in doing so reduces the need to understand the delivered structure. The downside is that re-use is simple and DOM manipulation for attribute handling is required. It is much easier to pick up and use, rather than implementing rules in code as prototype A has it will let the developer do as they wish and rules will have to be observed. So how I feel about them: Prototype A is complex. You would need to have a proper understanding of how it works before trying to utilise this functionality. Documentation would aid this - but really it is too complex. Prototype B I personally don't feel the re-use goes far enough and I lack to imagine how it could go further with the current handling of attributes and the lack of state handling without getting truly complex and perhaps a hacky.
          Hide
          Sam Hemelryk added a comment -

          There is a discussion about this going on in the original spec post in the forums.
          I've commented recently there with regards to the OO approach https://moodle.org/mod/forum/discuss.php?d=261202#p1134395

          I've also created a couple of further prototypes looking at how that OO apporach can be taken differently

          Show
          Sam Hemelryk added a comment - There is a discussion about this going on in the original spec post in the forums. I've commented recently there with regards to the OO approach https://moodle.org/mod/forum/discuss.php?d=261202#p1134395 I've also created a couple of further prototypes looking at how that OO apporach can be taken differently https://github.com/samhemelryk/moodle/compare/output_prototype_2 https://github.com/samhemelryk/moodle/compare/output_prototype_3
          Hide
          Sam Hemelryk added a comment -

          The approach taken in Prototype 5 is beginning to look very appealing:

          See this readme for details about this branch.

          Show
          Sam Hemelryk added a comment - The approach taken in Prototype 5 is beginning to look very appealing: https://github.com/samhemelryk/moodle/compare/output_prototype_5 See this readme for details about this branch.
          Hide
          Sam Hemelryk added a comment -

          Closing this - output renderable creation has been documented at http://docs.moodle.org/dev/Guide_to_creating_output_elements

          Show
          Sam Hemelryk added a comment - Closing this - output renderable creation has been documented at http://docs.moodle.org/dev/Guide_to_creating_output_elements

            People

            • Assignee:
              Sam Hemelryk
              Reporter:
              Sam Hemelryk
              Participants:
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Agile