When working with Liquid files for Theme Setup in PathFactory Templated Experiences, please follow the guidelines below for best-practice code organization and maintainability.
Selector Strategy
- Class Naming Conventions – Important:
- Do not change existing IDs or classes. To do so may cause their associated CSS or javascript to not work.
- Do not start a class name with a number, as it can lead to unexpected behavior.
- Consistency in class naming aids in better identification.
- Prefer Classes Over IDs: To enhance accessibility testing and prevent duplicate ID issues, prioritize using classes over IDs as primary selectors. Classes offer more versatility, allowing for multiple instances and varied selections, unlike IDs that are limited to one instance.
- Variable Declaration: Declare all selectors as liquid variables at the top of the file, particularly for selectors composed of multiple variables. This promotes clarity and allows for easy global changes if needed, minimizing the risk of errors due to incorrect event listeners.
- Crafting Unique Selectors: Create unique selectors using a specific format to avoid conflicts. Be mindful of duplicates and account for multiple component instances and different sections using the same component. Format: {{ Component_description }}-{{ node-id }}-{{ component-id }}-{{ specificity }}. These selectors should be in class format.
- Order of Specificity: Arrange selector IDs in a top-down order based on the DOM hierarchy. This ensures a consistent and logical structure for easier identification.
- Selector Construction: Avoid Ancestor Chains. Minimize the use of ancestor chain selectors (e.g., “.parent > .child > .target”) and opt for containment selectors instead (e.g., “.parent .target”). Contain-selectors are more robust, as changes to the hierarchy won’t break the selector’s functionality.
Component Development
- Props Declaration: Components accepting props should clearly define the expected props at the beginning of the file and provide example values. This documentation simplifies component usage for others.
- JavaScript Placement: Whenever possible, keep JavaScript code within the files where it is used. For instance, if a button component has a click event listener, place the listener in that component’s file. This approach offers better context and clarity.
- Exceptions: In cases of reusable functions, place them in a suitable common file, like the helpers folder, to ensure organized and manageable code.
Views: 13