Civiform: Enhanced Enumerator Usability - No More '$this' Requirement

by Alex Johnson 70 views

Civiform is getting a usability boost! This update focuses on simplifying the process of creating repeated questions, specifically addressing the often confusing requirement of using 'this′or′this' or 'this.parent' in the question text. This enhancement aims to make the question creation process more intuitive for administrators, ultimately leading to a better user experience. This change will be implemented behind a feature flag, allowing for controlled testing and deployment.

Understanding the Issue: The '$this' Conundrum

Currently, when an administrator creates a new repeated question in Civiform, the system mandates the inclusion of 'this′or′this' or 'this.parent' within the question text. This requirement, while functional, can be perplexing for users who are not familiar with the underlying logic. The purpose of 'this′istoactasaplaceholderthatdynamicallyinsertsthenameoftheenumeratedentity(e.g.,ahouseholdmember)intothequestion.Whiletechnicallysound,thisapproachintroducesanunnecessarylayerofcomplexityforadministratorswhosimplywanttophrasetheirquestionsinaclearandnaturalmanner.∗Thecurrentsystemenforcesthisrequirement∗,evendisplayingamessagepromptingtheusertoinclude′this' is to act as a placeholder that dynamically inserts the name of the enumerated entity (e.g., a household member) into the question. While technically sound, this approach introduces an unnecessary layer of complexity for administrators who simply want to phrase their questions in a clear and natural manner. *The current system enforces this requirement*, even displaying a message prompting the user to include 'this' and preventing them from saving the question if it is absent. This can lead to frustration and a steeper learning curve for new users.

**Our goal is to remove this mandatory requirement while still supporting the use of 'this′foradvanceduserswhoprefertheexplicitplaceholderapproach.∗∗Thiswillinvolvemodifyingthequestioncreationformtoallowadministratorstosavequestionswithoutincluding′this' for advanced users who prefer the explicit placeholder approach.** This will involve modifying the question creation form to allow administrators to save questions without including 'this'. The system will need to be updated to intelligently handle cases where 'this′isnotpresent,potentiallyinferringtheintendedentityfromthecontextofthequestionorprovidingalternativemechanismsforspecifyingtheentity.Thischangedirectlyaddressesthefeedbackfromadministratorswhofoundthe′this' is not present, potentially inferring the intended entity from the context of the question or providing alternative mechanisms for specifying the entity. This change directly addresses the feedback from administrators who found the 'this' requirement to be confusing and unnecessary.

Furthermore, we need to re-evaluate the message that currently prompts users to use 'this′.Themessagemayneedtoberemovedentirelyormodifiedtoprovideclearerandmorehelpfulguidance.Thisdecisionwillbemadeinconsultationwiththeproductteamtoensurethattheupdatedmessagealignswiththeoveralluserexperiencegoals.Byremovingthemandatory′this'. The message may need to be removed entirely or modified to provide clearer and more helpful guidance. This decision will be made in consultation with the product team to ensure that the updated message aligns with the overall user experience goals. By removing the mandatory 'this' requirement and refining the accompanying messaging, we aim to create a more intuitive and user-friendly question creation process in Civiform. This will empower administrators to create effective and engaging questionnaires with greater ease and efficiency, ultimately benefiting both the administrators and the applicants who use the system.

The Proposed Solution: Flexibility and User-Friendliness

The core of the solution lies in decoupling the question text from the strict 'this′requirement.Administratorsshouldbeabletophrasequestionsnaturally,withoutbeingforcedtouseatechnicalplaceholder.Thismeansthesystemneedstobeintelligentenoughtounderstandthecontextofthequestionandinfertheintendedentity,orprovidealternativewaystospecifytheentitybeingreferenced.∗Thiswillrequirechangestothequestioncreationformandtheunderlyinglogicthatprocessesandrendersquestions∗.We′llmaintainsupportfor′this' requirement. Administrators should be able to phrase questions naturally, without being forced to use a technical placeholder. This means the system needs to be intelligent enough to understand the context of the question and infer the intended entity, or provide alternative ways to specify the entity being referenced. *This will require changes to the question creation form and the underlying logic that processes and renders questions*. We'll maintain support for 'this' for those who find it useful, ensuring backward compatibility and flexibility. This can be particularly beneficial when creating more complex or dynamic question structures where the explicit use of '$this' provides greater control and clarity.

This approach offers a significant improvement in user experience. New administrators will find the question creation process more intuitive, as they can focus on the content of the questions rather than grappling with technical requirements. Existing administrators who are comfortable with 'this′cancontinuetouseit,whilethosewhopreferamorenaturalphrasingstylewillhavethefreedomtodoso.∗Thisflexibilitycaterstoawiderrangeofuserpreferencesandskilllevels∗.Theupdatedsystemwillneedtobethoroughlytestedtoensurethatitcorrectlyhandlesquestionswithandwithout′this' can continue to use it, while those who prefer a more natural phrasing style will have the freedom to do so. *This flexibility caters to a wider range of user preferences and skill levels*. The updated system will need to be thoroughly tested to ensure that it correctly handles questions with and without 'this', and that the intended entity is always correctly referenced. This testing will involve creating a variety of different question types and scenarios to identify and address any potential issues. By implementing this solution, we aim to create a more inclusive and user-friendly Civiform experience, empowering administrators to create effective and engaging questionnaires with greater ease and confidence.

Implementation Details: Feature Flag and Messaging

The changes will be rolled out behind a feature flag. This allows us to test the new functionality with a subset of users before making it available to everyone. This phased rollout approach helps minimize risk and allows us to gather valuable feedback from real users before fully deploying the changes. The feature flag also provides a convenient mechanism for reverting to the old behavior if any unexpected issues arise.

**The messaging around 'this′willalsobeaddressed.∗∗Weneedtodeterminewhethertoremovetheexistingmessagethatpromptsuserstouse′this' will also be addressed.** We need to determine whether to remove the existing message that prompts users to use 'this', or to modify it to provide clearer and more helpful guidance. This decision will be made in consultation with the product team, taking into account the overall user experience goals. If the message is retained, it will need to be reworded to explain the purpose of 'this′inamoreaccessiblewayandtoemphasizethatitsuseisoptional.Theupdatedmessageshouldalsoprovideexamplesofhowtophrasequestionsbothwithandwithout′this' in a more accessible way and to emphasize that its use is optional. The updated message should also provide examples of how to phrase questions both with and without 'this', to help users understand the different approaches. By carefully considering the messaging, we can ensure that administrators are properly informed about the use of '$this' and can make informed decisions about how to phrase their questions.

This approach ensures a smooth transition to the new functionality and allows us to gather valuable feedback from users before making it widely available. The feature flag provides a safety net, allowing us to quickly revert to the old behavior if any unexpected issues arise. By carefully managing the rollout and messaging, we can ensure that the changes are well-received and that administrators are able to take full advantage of the improved question creation process.

Testing and Validation: Ensuring a Seamless Experience

Thorough testing is crucial to ensure that the new system functions correctly and provides a seamless user experience. The testing process will involve creating a wide range of different question types and scenarios, both with and without '$this'. We will need to verify that the system correctly handles questions in both cases, and that the intended entity is always correctly referenced.

The testing will cover various aspects of the system, including:

  • Question creation: Verifying that administrators can create and save questions without using '$this'.
  • Question rendering: Ensuring that questions are displayed correctly to applicants, with the appropriate entity names inserted.
  • Data processing: Confirming that the system correctly processes responses to questions, regardless of whether '$this' was used in the question text.

The testing will be conducted by a team of testers, including both developers and non-technical users. This will ensure that the system is tested from a variety of perspectives and that any usability issues are identified and addressed. The testing process will also involve automated tests to ensure that the system continues to function correctly as new features are added and changes are made. By conducting thorough testing, we can ensure that the new system is robust, reliable, and user-friendly.

Done Criteria: Defining Success

This issue is considered complete when the following criteria are met:

  • **'this′isnolongermandatory:∗∗Whencreatinganewquestionbehindthefeatureflag,itisnotnecessarytouse′this' is no longer mandatory:** When creating a new question behind the feature flag, it is not necessary to use 'this' in the question text.
  • **'this′isstillsupported:∗∗Whencreatinganewquestion,itisstillpossibletouse′this' is still supported:** When creating a new question, it is still possible to use 'this' if desired, and the placeholder is still replaced with the listed entity name on the applicant side.
  • Messaging is updated: The message prompting users to use '$this' is either removed or modified, depending on the product team's decision.

Additional Context and Resources

For more details, refer to this section of the TDD.

To understand the current behavior:

  1. Log in as an administrator.
  2. Navigate to the "Questions" tab.
  3. Click the "Create new question" button.
  4. Select any question type except "Enumerator."
  5. In the Question Enumerator dropdown, choose an enumerator question.
  6. Observe the message instructing you to use '$this,' and note that saving the question is impossible without it.

By meeting these criteria, we can ensure that the new system is a significant improvement over the old one, and that it provides a better experience for both administrators and applicants. For additional information on web content accessibility guidelines, consider visiting the WCAG official website.