[Accepted with Revisions] SDL 0321 - Add Current Template Name to Window Capabilities
theresalech opened this issue · 19 comments
Hello SDL community,
The review of "SDL 0321 - Add Current Template Name to Window Capabilities" begins now and runs through October 27, 2020. The proposal is available here:
Reviews are an important part of the SDL evolution process. All reviews should be sent to the associated Github issue at:
What goes into a review?
The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of SDL. When writing your review, here are some questions you might want to answer in your review:
- Is the problem being addressed significant enough to warrant a change to SDL?
- Does this proposal fit well with the feel and direction of SDL?
- If you have used competitors with a similar feature, how do you feel that this proposal compares to those?
- How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
Please state explicitly whether you believe that the proposal should be accepted into SDL.
More information about the SDL evolution process is available at
https://github.com/smartdevicelink/sdl_evolution/blob/master/process.md
Thank you,
Theresa Lech
Program Manager - Livio
theresa@livio.io
1. I believe we should add documentation to both this proposal and the RPC changes that the values contained in the new param should only be of the values included in the PredefinedLayout enum.
2. Because of the fact that we have ran into this in other implementations when dealing with optional parameters, it should be clear in the proposal that if the param is not included it is assumed that the template that was previously supplied is still valid. Therefore, the HMI does not need to send this param if the template itself hasn't changed.
3
Currently, it's impossible for an app developer to know what the current template name is when they first connect.
I think it's good to add a template name parameter,
However, I think that the template when connecting for the first time should be the mechanism specified by the application developer.
4
It is better to have a perfectly reliable update whenever the template changes that speaks to which template is being referred to.
You should include a sample code on how to use this parameter for a perfectly reliable update.
1. Because the template doesn't have to be a PredefinedLayout (https://github.com/smartdevicelink/rpc_spec/blob/master/MOBILE_API.xml#L3105), I don't think that we can say here that it should only be a value in the PredefinedLayout enum, because while it probably will be, our API is defined in a way such that it doesn't have to be. I could extend the description of the parameter to contain information like Predefined or dynamically created window template. Predefined template names are defined in the PredefinedLayout enum.
2. I agree and can add that.
3. Are you asking to add an additional API to the RegisterAppInterface to have the developer set their initial template? The problem with that is that the developer doesn't know what templates are available on the head unit until after the registration.
4. I'm not sure what you're asking here. In iOS you'd use the parameter like print(windowCapability.template)
The Steering Committee voted to keep this proposal in review, to allow for further discussion on the review issue.
@joeljfischer -san,
Thanks for your reply.
3
It does not mean that the developer sets the initial template in RegisterAppInterface,
but that the app developer should explicitly specify the template to display in SetDisplayLayout.
After all, if you have to worry about what your current Template is while designing it,
I think it is better to recommend making a template by specifying it from the beginning.
Because you'll be specifying a Template if it's not the one you were expecting.
How about the above as an alternative idea?
4
I'm sorry for the unclear question.
I understand how to check the parameters.
I'm asking about the downside 2 that says,
“It is better to have a perfectly reliable update whenever the template changes that speaks to which template is being referred to."
I would like to know that what should a developer design if he or she wants to do so and that if there is a recommended design, wouldn't it be better to show it in sample code, like BestPractice.
3. I'm sorry, but I'm not understanding your point here. Of course the developer can manually set the layout themselves using an RPC / ScreenManager API, but while we could mandate that developers do that in their code, that would be a breaking change and is undesirable for other reasons. It's also unnecessary for many apps (such as MEDIA apps).
4. That sentence refers to proposed solution, so the developer would use the proposed solution as defined in the proposal. If that's not a sufficient answer for you, I'm afraid I don't understand the question.
@joeljfischer -san,
3
Currently, it's impossible for an app developer to know what the current template name is when they first connect.
For this motivation
Why is this impossible?
I think it is important to solve the problem itself.
For example, if the problem is that the default is different depending on the OEM, it is better to make the default common to the OEM or specify what the app displays.
In this proposal, getting the current template only helps you decide if you want to switch templates, it doesn't solve the defaults that aren't what you expected. I don't think it will be a fundamental solution.
4
In relation to 3, I think that the implementation method will be specified (recommended) when making a fundamental solution, so it is necessary to prepare samples and skeletons to make it easier to develop and modify.
The app developer has to look at this proposal to know that when he or she gets a current templte, it needs to be handled appropriately if the Default is not what it would be expected.
And he or she doesn't know the specific implementation.
The above situations should be avoided.
3. I think I understand what you're saying. I think you're asking if I could add documentation to the HMI integration guides or overview guides to guarantee for certain kinds of apps what the starting template is. Can you please confirm that that is what you are asking? If so, I don't see a problem with that, but I also don't think that this is a necessarily contradictory proposal. The head unit should still confirm to the device that their assumption of what template they are on is correct.
4.
I think that the implementation method will be specified (recommended) when making a fundamental solution, so it is necessary to prepare samples and skeletons to make it easier to develop and modify.
Are you asking for documentation on what an app developer would do here? Either way, this is simple and completely dependent on what the developer wants to do, and therefore is incredibly variable. Documentation is always added for new features on smartdevicelink.com in the app library guides and would be done again here. There's really nothing to document here because the developer gets the information (by simply pulling from the property) and then doing whatever they wish based on that, which can't really be documented. I strongly disagree that "skeletons" and "samples" are at all necessary for this very simple change.
3
I think you're asking if I could add documentation to the HMI integration guides or overview guides to guarantee for certain kinds of apps what the starting template is.
We believe this is one of the solutions to the problem.
We expect that the problem is "The Default template may be different for each OEM, and the template may be different from what App Developer expected, so it will not be displayed correctly."
Therefore, we think the above is one of the solutions.
Another option is to "make sure the App developer specifies a Template".
If our perception is not match, could you explain to us the problem?
We think it is better to clarify the current problem and then discuss and describe the solution to the problem.
4
Are you asking for documentation on what an app developer would do here?
Yes.
There's really nothing to document here because the developer gets the information (by simply pulling from the property) and then doing whatever they wish based on that, which can't really be documented.
We think it is necessary to separate what the app developer wants to do and what the system must do.
We think that this proposal corresponds to what the application developer must do as a system, not what he wants to do.
In this case, we don't think it's better for the app developer to have to find out how to do it and think about it.
It may be better for the app developer if the method is presented or hidden.
3.
We expect that the problem we are trying to solve with this proposal is"The Default may be different for each OEM, and the template may be different from what you expected from the App side, so it will not be displayed correctly."
This is incorrect. Allow me to quote from the motivation of this proposal:
The only way to track what the current template name is at any time after that is to track the SetDisplayLayout / Show request and responses. The window capability should contain information about the current template name in addition to its capabilities.
The problem is that the head unit nowhere declares "this is the template being displayed," and the app library SDKs nowhere say, "this is the template being displayed." Therefore, an API is being added on both ends to have a 100% reliable mechanism to say "this is the template being displayed." Adding documentation requiring OEMs to start on certain templates based on app types is fine, but it doesn't solve the problem for already released head units and it doesn't solve the problem in the motivation.
4.
Are you asking for documentation on what an app developer would do here?
Yes.
That is a request that I will not do for the reasons I already laid out in my previous comment. I believe that the problem and the solution have been described in detail and it is easily understandable.
We think it is necessary to separate what the app developer wants to do and what the system must do.
This is an extremely simple change. The system states what the current template is in the WindowCapability update.
In this case, we don't think it's better for the app developer to have to find out how to do it and think about it.
It may be better for the app developer if the method is presented or hidden.
I'm sorry, but are you saying that the app developer shouldn't know what template is displayed? If so, then I couldn't more strongly disagree with that as an app developer myself.
We will confirm joel-san comment and reply.
By the way, we are not against Joel's idea. we have the impression that it is not a fundamental solution to the problem, so we are posting question about it.
The Steering Committee voted to keep this proposal in review, to allow for additional conversation on the review issue.
3
The problem is that the head unit nowhere declares "this is the template being displayed," and the app library SDKs nowhere say, "this is the template being displayed." Therefore, an API is being added on both ends to have a 100% reliable mechanism to say "this is the template being displayed."
Are you suggesting that this proposal is simply an improvement in reliability by adding a parameter?
The motivation in this proposal states:
Currently, it's impossible for an app developer to know what the current template name is when they first connect.
We recognized that it's trying to solve the problem mentioned in this statement.
In other words, I would appreciate if you could clarify in the proposal whether the purpose of this proposal is to solve some problem or a proposal to simply improve.
3. Yes, by having this parameter, we solve the problem of not knowing with 100% certainty what the current template name is because the head unit is telling us.
The purpose of this proposal is to solve the problem of the app developer not knowing what the current template name is by adding the app library API, and to add an API to the window capability for the head unit to say "this is the current template name."
I feel that we are going around in circles, and I have said the same thing many times, so I request that the steering committee vote on this proposal in the next meeting.
Revisions:
1. Change the WindowCapability.template description to be "Predefined or dynamically created window template. Currently only predefined window template layouts are defined."
2. Clarify that if the parameter isn't provided after it has been provided previously, it should be assumed that the template has not changed.
3
We don't think there is any problem with the proposed function itself.
However, although this proposal can be implemented in various ways for each app, we mention that there is a concern that the implementation for each app will be different because the specific design is not shown.
We can agree if this proposal is incorporated into the environment or sample that the app developer is based on to avoid variability from app to app.
The Steering Committee voted to accept this proposal with revisions. The author will update the proposal to include the revisions described in this comment.
@joeljfischer please advise when a new PR has been entered to update the proposal to reflect the agreed upon revisions. I'll then merge the PR so the proposal is up to date, and enter issues in impacted repositories for implementation. Thanks!
The proposal has been updated and implementation issues have been entered: