{"id":13594610,"url":"https://github.com/trivule/trivule","last_synced_at":"2025-04-09T07:33:16.497Z","repository":{"id":154096773,"uuid":"631775609","full_name":"trivule/trivule","owner":"trivule","description":"Trivule is a powerful, user-friendly JavaScript library designed to streamline form validation for developers","archived":false,"fork":false,"pushed_at":"2024-05-28T15:07:43.000Z","size":516,"stargazers_count":47,"open_issues_count":6,"forks_count":8,"subscribers_count":2,"default_branch":"1.x","last_synced_at":"2024-06-12T16:51:52.406Z","etag":null,"topics":["form-validation","form-validation-js","validate-form","validation","validator"],"latest_commit_sha":null,"homepage":"https://www.trivule.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trivule.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-24T03:04:06.000Z","updated_at":"2024-08-01T16:39:12.624Z","dependencies_parsed_at":"2024-08-01T16:54:00.913Z","dependency_job_id":null,"html_url":"https://github.com/trivule/trivule","commit_stats":null,"previous_names":["trivule/trivule"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivule%2Ftrivule","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivule%2Ftrivule/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivule%2Ftrivule/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivule%2Ftrivule/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trivule","download_url":"https://codeload.github.com/trivule/trivule/tar.gz/refs/heads/1.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223375393,"owners_count":17135363,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["form-validation","form-validation-js","validate-form","validation","validator"],"created_at":"2024-08-01T16:01:36.456Z","updated_at":"2024-11-06T16:31:38.645Z","avatar_url":"https://github.com/trivule.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Trivule\n\nTrivule is a powerful, user-friendly JavaScript library designed to simplify form validation for developers. It is a ready-to-integrate solution for modern framworks.\n\nTo get started with Trivule, please refer to the comprehensive documentation available [here](https://www.trivule.com). You can also follow a quick tutorial of less than 5 minutes [here](https://trivule.com/docs/tuto) to familiarize yourself with Trivule.\n\n## Key Features\n\n**Imperative Validation Approach**\n\n```js\nconst trivuleForm = new TrivuleForm('form', {\n  feedbackSelector: '.invalid-feedback',\n  realTime: true,\n});\n\ntrivuleForm.make({\n  email: {\n    rules: ['required', 'email', 'maxlength:60'],\n    feedbackElement: '.invalid-feedback',\n  },\n});\n\ntrivuleForm\n  .get('email')\n  .appendRule({\n    rule: 'endWith:@gmail.com',\n  })\n  .removeRule('maxlength');\n```\n\n- **Streamlined Validation**: Implement complex validation rules without the hassle. Trivule simplifies your workflow, allowing you to focus on building better user experiences.\n- **Time-Saving**: With Trivule, save valuable time that you can invest in other critical aspects of your project.\n- **Dynamic Conditional Validation**: Adapt to user inputs in real-time, providing dynamic responses and validations as conditions change.\n- **Framework Compatibility**: Seamlessly integrate with modern frameworks using a consistent interface\n\n**Declarative Validation Approach**\n\n```html\n\u003cinput name=\"email\" type=\"text\" data-tr-rules=\"required|email|maxlength:60\" /\u003e\n\u003cdiv data-tr-feedback=\"email\" class=\"invalid-feedback\"\u003e\u003c/div\u003e\n```\n\n- **HTML/CSS-Based Validation**: Perfect for quickly setting up validations using just HTML and CSS. Ideal for projects where simplicity and speed are key.\n- **Time Efficiency**: Minimize the time spent on scripting validations. Set up once, and let Trivule handle the rest.\n- **Intuitive Syntax**: User-friendly attributes make implementing validation rules straightforward, even for those with minimal coding experience.\n- **Conditional Validation Ready**: Easily set up conditions for your validations to handle complex scenarios with ease.\n\n**Error Messaging \u0026 Localization**\n\n```js\ntrivuleForm.make({\n  email: {\n    rules: ['required', 'email', 'maxlength:60'],\n    messages: [\n      'The field is required',\n      'The email is invalid',\n      'The email is too long',\n    ],\n  },\n});\n\n//Global Translation\nTrLocal.translate('es', {\n  required: 'El campo es obligatorio',\n});\n\n//Global modification of an existing message\nTrLocal.rewrite('en', 'required', 'The :field cannot be empty');\n```\n\n```html\n\u003cinput\n  name=\"email\"\n  type=\"text\"\n  data-tr-rules=\"required|email|maxlength:60\"\n  data-tr-messages=\"The field is required|The email is invalid|The email is too long\"\n/\u003e\n```\n\n- **Customizable Error Messages**: Tailor error messages to fit the context of your application, enhancing user guidance and experience.\n- **Localization Support**: Extend your application’s reach with built-in support for multiple languages, making your forms globally accessible.\n- **Smart Feedback Management**: Intelligent error feedback ensures users are clearly informed about validation issues, improving form completion rates.\n\n**Robust Validation Rules**\n\n```js\nconst rules = ['email', 'size:1GB', 'before:now'];\n```\n\n- **Intuitive and Understandable Rules**: Each rule is designed to be self-explanatory, providing clear guidance and reducing the learning curve.\n- **Extensive Rule Set**: Cover a wide array of scenarios with Trivule’s comprehensive library of predefined validation rules.\n- **Easily Extendable**: Add or customize rules as your application requirements grow or change.\n- **Rewrite Existing Rules**: Adapt the library to meet specific needs by rewriting existing rules, offering unparalleled flexibility.\n\n**Trivule** is your go-to solution for making form validation not just possible but also a pleasant part of user interactions. Whether you are a developer looking to streamline your workflow or a business aiming to improve user experience, Trivule provides the tools you need to succeed. Start simplifying your forms with Trivule today!\n\n### Validation Made Simple\n\nEffortlessly validate inputs using Trivule, saving valuable development time. Utilize the `data-tr-rules` attribute to define validation rules directly in your HTML:\n\n```html\n\u003cinput type=\"text\" data-tr-rules=\"required|integer|between:16,50\" name=\"age\" /\u003e\n```\n\nor in javascript\n\n```js\ntrivuleForm.make({\n  age: {\n    rules: 'required|integer|between:16,50',\n  },\n});\n```\n\nDisplay error messages with ease using the `data-tr-feedback` attribute:\n\n```html\n\u003cdiv data-tr-feedback=\"age\"\u003e\u003c/div\u003e\n```\n\nor in javascript\n\n```js\ntrivuleForm.make({\n  age: {\n    rules: 'required|integer|between:16,50',\n    feedbackElement: '[data-tr-feedback=\"age\"]', //or [data-tr-feedback]\n  },\n});\n```\n\n## Event-Based Validation\n\nTrigger validation on specific events using the `data-tr-events` attribute, eliminating the need for additional JavaScript code:\n\n```html\n\u003cinput type=\"text\" data-tr-events=\"blur|change\" name=\"age\" /\u003e\n```\n\nor in javascript\n\n```js\ntrivuleForm.make({\n  age: {\n    rules: 'required|integer|between:16,50',\n    events: ['blur', 'change'],\n  },\n});\n```\n\n### Custom Styling\n\nStyle your inputs dynamically based on validation results using `data-tr-invalid-class` or `data-tr-valid-class` attributes:\n\n```html\n\u003cinput\n  type=\"text\"\n  data-tr-invalid-class=\"error\"\n  data-tr-valid-class=\"success\"\n  name=\"age\"\n/\u003e\n```\n\nor in javascript\n\n```js\ntrivuleForm.make({\n  age: {\n    rules: 'required|integer|between:16,50',\n    invalidClass: 'error',\n    validClass: 'success',\n  },\n});\n```\n\n### Custom Error Messages\n\nBy default we provide a message for each rul e but you can customize error messages to align with your project's requirements using the `data-tr-messages` attribute:\n\n```html\n\u003cinput\n  type=\"text\"\n  data-tr-messages=\"This field is required | Another message\"\n  name=\"age\"\n/\u003e\n```\n\nor in javascript\n\n```js\ntrivuleForm.make({\n  age: {\n    rules: 'required|integer|between:16,50',\n    messages: 'This field is required |This field must be an integer',\n  },\n});\n```\n\n### Add or Edit Rule\n\nFor adding or editing a rule in Trivule, you can play with `TrRule` class\n\n```javascript\nTrRule.add('notSudo', (input) =\u003e {\n  return {\n    value: input,\n    passes: input != 'sudo',\n  };\n});\n```\n\n[Get Started with Trivule](https://www.trivule.com/docs)\n\n\n## Usage Guide in a Framework\n\nWelcome to the Trivule installation and usage guide.\n\n### Install Trivule with npm\n\nInstall Trivule in your project. This guide uses Trivule version v1.3.0. If you are using an older version, you should migrate to version v1.3.0.\n\n```sh\nnpm install trivule\n```\n### Imperative Approach\n\nThe imperative approach requires explicit control over your project's lifecycle and component initialization.\n\n#### Your Framework lifecyle\n\n- **Unique Initialization**: Avoid initializing `TrivuleForm` in a frequently called hook. Prefer initializing it outside of a hook if possible to avoid repeated reinitializations.\n- **Form Element Lookup**: Use the `bind` method to locate the form element to be validated. This lookup is performed only once for optimal performance. Ensure the DOM is ready before calling this method. You can call it in a hook that indicates the form is ready.\n\n#### Using the afterBinding Hook\n\nUse the `afterBinding` hook to register your callbacks, which will be executed as soon as the form element is available.\n\nExample:\n\n```javascript\nimport TrivuleForm from 'trivule';\n\nconst form = new TrivuleForm();\n\n// Define your validation rules here\nform.afterBinding((form) =\u003e {\n  form.make({\n    fieldName: {\n      rules: \"required|min:2\"\n    }\n  });\n});\n\n// React\nuseEffect(() =\u003e {\n  form.bind(/*selector*/);\n}, []);\n\n// Angular\nngAfterViewInit() {\n  form.bind(/*selector*/);\n}\n\n// Vue\nmounted() {\n  form.bind(/*selector*/);\n}\n\n//etc\n```\n\n### Important Points\n\n- `bind` only executes code after finding the target element.\n- Trivule does not monitor the DOM to check if your element is available. Call the `bind` method when you are certain the `form` is in the DOM.\n\n### Declarative Approach\n\n1. **Define the Form**: Ensure your form is correctly defined with declarative attributes.\n2. **Call the bind Method**: Do this when the form is available in the DOM.\n\nExample:\n\n```html\n\u003cform id=\"yourFormId\"\u003e\n  \u003cinput type=\"text\" name=\"fieldName\" data-tr-rules=\"required|min:2\"\u003e\n\u003c/form\u003e\n```\n\n## Quick start\n- [Single Input Validation](/docs/input-validation.md)\n- [Form Validation](/docs/form-validation.md)\n\n## Development\n\nIf you would like to contribute to the development of Trivule or customize the library, here's what you need:\n\n### Prerequisites\n\n- Node.js \u003e= 16\n- npm installed\n- Knowledge of TypeScript\n\n### Installation\n\nTo clone and install the Trivule project, follow these steps:\n\n1. Clone the project using the following command:\n   ```bash\n   git clone https://github.com/trivule/trivule.git\n   ```\n2. Navigate to the project's root directory.\n3. Install the dependencies by running the following command:\n   ```bash\n   npm install\n   ```\n4. If the installation is successful, start the development server with the following command:\n   ```bash\n   npm run dev\n   ```\n   This will start a local development server, and a link to the Trivule homepage (e.g., `http://localhost:5173`) will be displayed in your terminal. You can start testing by editing the `/src/example.ts`, which relates to the `index.html` file.\n\nTo create the bundles, run the following command:\n\n```bash\nnpm run build\n```\n\nThis command will generate the `index.mjs` and `index.umd.js` files in the `./dist` folder. The first file is intended for use as an ES6 module, while the second file is suitable for UMD systems. You can also use the `npm run build:watch` command to automatically compile files while you work.\n\n### Directory Structure\n\nThe directory structure of the Trivule project is organized as follows:\n\n- `src`: contains the main code of Trivule.\n- `src/contracts`: contains interfaces and types used in Trivule.\n- `src/locale`: contains internationalization files for different supported languages.\n- `src/messages`: contains message generation files based on validation rules.\n- `src/rules`: contains various validation rules available in Trivule.\n- `src/utils`: contains utility files for Trivule.\n- `src/validation`: contains the validation logic of Trivule.\n- `dist`: contains the bundle files.\n- `types`: contains TypeScript declarations.\n\n## Contribution\n\nThe Trivule library is available on [GitHub](https://github.com/trivule/trivule) under an open-source license. We welcome contributions from the community. Please refer to our [contribution guidelines](https://trivule.com/docs/contribution) for more information and review our [code of conduct](https://trivule.com/docs/contribution#code-de-conduite) before contributing. Thank you to all the contributors who are involved in the development of Trivule.\n\n## Community\n\nJoin the Trivule community:\n\n- Discord: [https://discord.gg/6xKyDWA8TQ](https://discord.gg/6xKyDWA8TQ)\n- X: [https://twitter.com/trivule](https://twitter.com/trivule)\n\n## License\n\nTrivule is released under our [license](http://www.trivule.com/docs/license) and developed by [Claude Fassinou](https://github.com/Claudye) and contributors.\n\nBest regards\n\n## Security\n\nIf you discover any security-related issues, please contact me directly at [dev.claudy@gmail.com ](mailto:dev.claudy@gmail.com) instead of using the issue tracker.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrivule%2Ftrivule","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrivule%2Ftrivule","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrivule%2Ftrivule/lists"}