GSoC proposal for Support the ‘maps’ parameter in TemplateData Editor (GUI)"
Closed, ResolvedPublic
Actions

Description

Supporting the ‘maps’ parameter in TemplateData Editor (GUI)

Name: Adham Essam Khatean
IRC nick: aekhatean
User Page: https://www.mediawiki.org/wiki/User:AdhamKhatean
Github: https://github.com/aekhatean
Location: Damanhuor, Egypt.
Time Zone: Eastern European Time (EET) / (UTC+2).
Typical working hours: 4 PM to 2 AM (UTC+2).

Why MediaWiki?
Since I was a kid I always landed on some Wikipedia page when I am trying to learn about something that I am curious about. It was always my initial point of understanding a lot of concepts that I know now that made me interested in the things I am interested in. And you “the things that interest you define you” So you can say Wikipedia has a role of making me who I am today by making knowledge easily accessible. And now I want to give back to this great community and hopefully be part of it through contributing to its open source. And I think GoSC will be a great beginning as through this program I can have a mentor to help through the codebase and the communication of the MediaWiki community which is the engine of Wikipedia and other Wikimedia projects.

Why TemplateData?
When I decided to contribute to MediaWiki, I installed it on my device and it was fairly normal to do something once you know how to do it. Unlike using it as an editor it was quite challenging to do something and it takes some time to get familiar with it. But when I tried using extensions like TemplateData it became easier for me as a user to modify templates, As it provided me with simple and efficient GUI. But, adding or modifying a map in the template is still complicated for a user and uses JSON syntax. So, I am interested in this project because I want to help make it easier for contributors to Wikimedia projects to share their knowledge with us, especially as this project will substitute manual editing dependent on JSON to a simple GUI.

Synopsis
TeplateData is a MediaWiki extension that was created to improve the template-editing experience for the user. Making it less confusing by providing the user with a list of suggested parameters and a description of every parameter of the template and what values are acceptable which makes it easier and also more time-efficient for the user to modify the template.
However, the TemplateData GUI Editor does not support the “Maps” parameter, yet. which makes it a challenging task to modify this parameter compared to other parameters. So, this project aims to bring the maps parameter with its full functionality to the GUI editor to make it easier for the average non-technical user to modify the “Maps” parameter.

Technologies

JavaScript
Php
OO-UI
JSON

Deliverables

Adding the ‘maps’ parameter to the GUI editor.
Detailed documentation of the new parameter.
Unit Tests.

Timeline

Period	Task
May 4, 2020 - June 1, 2020	- `Community bonding period`, `Familiarizing myself with MediaWiki specific tools involved in TemplateData GUI like OO-UI`, and `Analyzing TemplateData codebase and its relations with Mediawiki core, other extensions, and the database`.
June 2, 2020 - June 17, 2020	- `Display text of maps value if present (not editable)`, `Adding a button ‘edit maps’ to the main panel of the GUI to access edit maps panel.`, `SAdding a multiline text input in the "edit maps" panel. So users can add and remove consumer keys and edit info Like ISSN, DOI, place, etc.`.
June 18, 2020 - June 28, 2020	- `Styling new fields with OO-UI like the rest of TemplateData GUI.`.
June 29, 2020 - July 3, 2020	- `Evaluation Phase I`.
July 4, 2020 - July 26, 2020	`Connecting the new Fields with the text editor to show them in the text editor as json encoded information to be shown and editable in the GUI editor. to be later decoded`.
July 27, 2020 - July 31, 2020	- `Evaluation Phase II`
Aug 1, 2020 - Aug 23, 2020	`Developing a mechanism to parse the input information into JSON.`,`Testing the new feature`, `Documenting this feature in detail with simplicity in mind`.
Aug 24, 2020 - Aug 31, 2020	- `Submit Code and Final Evaluations`.

Description

Using UX/UI friendly text box input fields to edit the JSON instead of leaving it exposed to the user, and the following figures might clarify the idea:
Instead of letting the user deal with something like that which might be confusing especially when JSON syntax errors occur,

We might make easier to use and more restrict so it does not make as many errors while saving the changes, but at the same time we still provide the user with some kind of flexibility by Creating new panel (Map Panel) which gives users the ability to modify maps object easily through TemplateData GUI instead of the text editor.

So, taking a simple map for example, instead of inserting map info like this:

“Maps”: {
    “Temp”: {
		“Title”: “title”,
		“Author”: “name”,
		“Date”: “date”
    }
}

Users can simply use this format:

Title: title
Author: name
Date: date

Which means:
1 – Map is an object that has its own specs, and will be shown as multiline text input instead of JSON syntax. This way it will be easier for the user with less cryptic symbols and also cause fewer errors.
2 – After users click the “Edit map” button, a new panel will appear showing map info that is already inserted and can also append more.

After the user adds the “Map” parameter with and its related information it will be parsed into JSON and added to the text editor (the same way as the rest of GUI editor).

Contributions to MediaWiki

Submitted a Contribution to T217516
Submitted a Contribution to T200385
Submitted a Contribution to T248486

Commitment

I am from Egypt. So, due to what my country is going through and the educational process being interrupted due to COVID-19 I might not be able to be active more than 20 - 25 hours starting from the 30th of May and for 3 - 4 weeks. As our exams in Egypt were postponed to at least the 30th of May.
For the rest of the duration of the program, I will be available for 40+ hrs a week.

Related Objects
Search...

Status	Assigned	Task
Open	None	T207139 Deprecate manual raw TemplateData JSON source editing
Resolved	AdhamKhatean	T208305 Support 'maps' parameter in TemplateData Editor (GUI)
Resolved	AdhamKhatean	T248267 GSoC proposal for Support the ‘maps’ parameter in TemplateData Editor (GUI)"
Resolved	AdhamKhatean	T254478 Create the initial UI of Maps panel in TemplateData GUI
Resolved	AdhamKhatean	T257503 Make the maps object editable from the TempateData dialog
Resolved	AdhamKhatean	T258820 Allow different maps to be edited separately in the TemplateData dialog

Event Timeline

AdhamKhatean created this task.Mar 22 2020, 6:41 PM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 22 2020, 6:41 PM

@Mvolz, @Tchanders, @Mooeypoo - Hello,
I am adham Khatean, an undergraduate student from Egypt pursuing degree in physics, I am interested in participating in "support maps parameter in TemplateData editor (GUI) " as a GSoC student.

That is my proposal for the project, and I was wondering if you have any advice on improving it? Especially on the timeline part? Do you think there is any thing that I miss understood about the idea or the extension TemplateData itself?
Would you any other micro tasks that you think might make me more understanding of the idea or the extension?

Thanks in advance.

In T248267#5997619, @AdhamKhatean wrote:

@Mvolz, @Tchanders, @Mooeypoo - Hello,
I am adham Khatean, an undergraduate student from Egypt pursuing degree in physics, I am interested in participating in "support maps parameter in TemplateData editor (GUI) " as a GSoC student.

That is my proposal for the project, and I was wondering if you have any advice on improving it? Especially on the timeline part? Do you think there is any thing that I miss understood about the idea or the extension TemplateData itself?
Would you any other micro tasks that you think might make me more understanding of the idea or the extension?

Thanks in advance.

Wow, really great that you already completed a microtask! You can also add us as reviewers on gerrit (mvolz is my username there) going forward for any patches as well, although I've had a look at the second one you're working on and it looks very challenging. ;)

Just some technical comments on this:

Adding custom fields related to the maps parameter. Like: ISSN, DOI, place, etc., Styling new fields with OO-UI like the rest of TemplateData GUI.

To me this "custom fields" sounds like adding hardcoded support for parameters like ISSN and DOI? Not sure if it's just that the language is unclear, but the fields in the the maps parameter can be literally anything, so those are good examples, but in the proposal it might make sense to make the language clearer here.

In general, I think a first step or minimally viable product might just be able to edit the raw JSON block in the gui too, but going straight to having the parameters be editable in a gui-like way seems good too if it's achievable. One challenge is the value for "maps" is more unstructured than it is for other keys like "params" or "description", which have a very defined structure.

And point two is, I'm not sure how much back-end php work is needed - I expect this to be possible to do nearly all of it as front end (although I could be wrong about that!) So overall I would say add more time for front end work and break that down more, in the proposal.

Thanks for the detailed proposal @AdhamKhatean. There's a suggested microtask here: T208305#5997816 - and we'll hopefully be able to add more to that list.

@Mvolz and @Mooeypoo may have more comments about the timeline, but one thing to note is that it has recently been extended to allow for reduced work capacity that many are experiencing at the moment: https://summerofcode.withgoogle.com/how-it-works/#timeline

To me this "custom fields" sounds like adding hardcoded support for parameters like ISSN and DOI? Not sure if it's just that the language is unclear, but the fields in the the maps parameter can be literally anything, so those are good examples, but in the proposal it might make sense to make the language clearer here.

What I was thinking about is:
Using UX/UI friendly text box input fields to edit the JSON instead of leaving it exposed to the user, and the following figures might clarify the idea:
Instead of letting the user deal with something like that which might be confusing especially when JSON syntax errors occur,

We might make easier to use and more restrict so it does not make as many errors while saving the changes, but in the same time we still provide the user with some kind of flexibility by adding “add field” button so they do less for more, Like this:

Which means:
1 - Name of the parameter does not have to be “map” which gives the user more freedom of picking their name: Map, Relations, Description, etc.
2 – Map is a type of parameters that has its own specs, and will be shown as text fields instead of JSON syntax. This way it will be easier for the user and also more restrict which can help us to push the best practice of this parameter.
3 – After users choose the “maps” type, a div will appear all the essentials of the map parameter and the ability to expand and add more. Like ISSN and DOI that also might be auto-generated using an API.

And point two is, I'm not sure how much back-end Php work is needed - I expect this to be possible to do nearly all of it as front end (although I could be wrong about that!) So overall I would say add more time for front end work and break that down more, in the proposal.

Here comes the usage of Php as a back-end that is compatible with HTML, which means it can take the data inserted by the user and parsing it to JSON using a Hook. And also deals with the API(s) used to generate data like serial number, DOI, ISSN –will appear for the user but the input field will not be editable- and push it to the user.
And the way that this should work is when the user interacts with extension to make the parameter of type “map” it runs a Hook that is registered in “TemplateDataHooks.php” to add this data to the JSON.

So, what do think?

@Tchanders - Thanks, I have seen the new timeline. I was just wondering if the timeline in this proposal seems reasonable or you think it is unrealistic and I underestimated something?

for more information that might help you decide, I will add a description for the idea in the proposal or you might check the previous comment it is the same thing.

And thanks for the recommendation of the microtask, I will check it out.

AdhamKhatean updated the task description. (Show Details)Mar 25 2020, 11:40 PM

Pavithraes assigned this task to AdhamKhatean.Mar 28 2020, 5:50 PM

AdhamKhatean updated the task description. (Show Details)Mar 28 2020, 8:19 PM

Hello @Mvolz, @Tchanders, @Mooeypoo - I hope you are fine.
I would like to know what do you think about the proposal and the project description? as I will have to submit my proposal soon.

Thanks in advance.

In T248267#6000424, @AdhamKhatean wrote:

And point two is, I'm not sure how much back-end Php work is needed - I expect this to be possible to do nearly all of it as front end (although I could be wrong about that!) So overall I would say add more time for front end work and break that down more, in the proposal.

Here comes the usage of Php as a back-end that is compatible with HTML, which means it can take the data inserted by the user and parsing it to JSON using a Hook. And also deals with the API(s) used to generate data like serial number, DOI, ISSN –will appear for the user but the input field will not be editable- and push it to the user.
And the way that this should work is when the user interacts with extension to make the parameter of type “map” it runs a Hook that is registered in “TemplateDataHooks.php” to add this data to the JSON.

This part should all be front-end, IMO. There's no reason to contact the back-end for this. It's easier to parse JSON with JavaScript than PHP anyway (and in fact our PHP JSON parser has a long standing bug!)

So, instead of directly storing the data inserted by the user from the GUI editor, we place them in the text editor using JS and it will be saved as usual we the user clicks "Save changes"? won't this make it harder for us to auto-generate things serial numbers, DOIs, ISSNs, etc? anyway if this does not seem achievable or unnecessary using Php, we can still do it with JS.

In T248267#6008966, @AdhamKhatean wrote:

So, instead of directly storing the data inserted by the user from the GUI editor, we place them in the text editor using JS and it will be saved as usual we the user clicks "Save changes"? won't this make it harder for us to auto-generate things serial numbers, DOIs, ISSNs, etc? anyway if this does not seem achievable or unnecessary using Php, we can still do it with JS.

I'm not sure what you mean by auto-generate - do you mean suggesting the template parameters to use in the map?

Think of it this way- what if someone adds a new parameter, 'foo' in the template data. This is in the front end. It is not yet saved. Then they want to add that the 'foo' parameter in the map as well - so we query the back end - but it is not saved yet, so it is not in the back-end! So we have to use the front end information anyway.

Since everything else is already being done in the front end, it doesn't make sense to save only the maps, when the rest of the template data is not saved yet. Better to keep it all in the front-end since that's how the existing code works anyway.

I'm not sure what you mean by auto-generate - do you mean suggesting the template parameters to use in the map?

Maps parameter is a way of JSON mapping the template and its parameters and their relationship with another set of parameters from another tool right? So, what I was thinking about is that some parameters can by TemplateData itself instead of leaving it for the user as it will not matter for the users to fill them by themselves. actually, it will make their workflow faster.

But, now that I get you I think it is out of this project scope. We might do it if it will be possible and useful after the GSoC period.

Thanks a lot.

In T248267#6010160, @AdhamKhatean wrote:

I'm not sure what you mean by auto-generate - do you mean suggesting the template parameters to use in the map?

Maps parameter is a way of JSON mapping the template and its parameters and their relationship with another set of parameters from another tool right? So, what I was thinking about is that some parameters can by TemplateData itself instead of leaving it for the user as it will not matter for the users to fill them by themselves. actually, it will make their workflow faster.

This is already done, by another tool. The user doesn't have to fill anything out by themselves already :).

AdhamKhatean updated the task description. (Show Details)Mar 30 2020, 1:09 PM

well, that is good we need to worry about any more. then we only need to focus on adding the maps parameter to the front-end.
could you please review this proposal for the last time before I upload it.

Mvolz moved this task from Accepted Proposals to Submitted Proposals on the Google-Summer-of-Code (2020) board.Apr 1 2020, 11:33 AM

srishakatux moved this task from Submitted Proposals to Accepted Proposals on the Google-Summer-of-Code (2020) board.Apr 7 2020, 7:05 PM

Aklapper added a parent task: T208305: Support 'maps' parameter in TemplateData Editor (GUI).Jun 5 2020, 11:47 AM

Aklapper mentioned this in T254478: Create the initial UI of Maps panel in TemplateData GUI.

Aklapper added a subtask: T254478: Create the initial UI of Maps panel in TemplateData GUI.

AdhamKhatean updated the task description. (Show Details)Jun 25 2020, 6:19 AM

Tchanders added a project: Anti-Harassment.Jul 8 2020, 6:23 PM

Tchanders moved this task from Untriaged to Onboarding Tasks on the Anti-Harassment board.

Niharika updated the task description. (Show Details)Jul 13 2020, 3:37 PM

Tchanders closed subtask T254478: Create the initial UI of Maps panel in TemplateData GUI as Resolved.Jul 14 2020, 3:43 PM

Tchanders closed subtask T257503: Make the maps object editable from the TempateData dialog as Resolved.Jul 24 2020, 6:21 PM

Tchanders closed subtask T258820: Allow different maps to be edited separately in the TemplateData dialog as Resolved.Sep 3 2020, 3:58 PM