{"id":19339797,"url":"https://github.com/owaiswiz/vc_shortcut","last_synced_at":"2025-04-23T02:30:55.559Z","repository":{"id":224382180,"uuid":"762843758","full_name":"owaiswiz/vc_shortcut","owner":"owaiswiz","description":"A simpler and less verbose-y way to render ViewComponents \u0026 Phlex components","archived":false,"fork":false,"pushed_at":"2024-04-18T04:03:46.000Z","size":49,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T10:46:05.635Z","etag":null,"topics":["phlex","rails","viewcomponents"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/owaiswiz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-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":"2024-02-24T21:00:59.000Z","updated_at":"2025-03-04T11:39:13.000Z","dependencies_parsed_at":"2024-02-25T17:24:27.648Z","dependency_job_id":"19389011-cbc2-49f9-b231-1f889e04ac92","html_url":"https://github.com/owaiswiz/vc_shortcut","commit_stats":null,"previous_names":["owaiswiz/vc_shortcut"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owaiswiz%2Fvc_shortcut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owaiswiz%2Fvc_shortcut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owaiswiz%2Fvc_shortcut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owaiswiz%2Fvc_shortcut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/owaiswiz","download_url":"https://codeload.github.com/owaiswiz/vc_shortcut/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250357571,"owners_count":21417308,"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":["phlex","rails","viewcomponents"],"created_at":"2024-11-10T03:23:54.007Z","updated_at":"2025-04-23T02:30:55.262Z","avatar_url":"https://github.com/owaiswiz.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VcShortcut\n\u003ca href=\"https://badge.fury.io/rb/vc_shortcut\"\u003e\u003cimg src=\"https://badge.fury.io/rb/vc_shortcut.svg\" alt=\"Gem Version\" height=\"18\"\u003e\u003c/a\u003e \u003cimg alt=\"Gem Total Downloads\" src=\"https://img.shields.io/gem/dt/vc_shortcut\"\u003e\n\nVcShortcut simplifies the API for rendering [ViewComponent](https://viewcomponent.org/)s and [Phlex](https://www.phlex.fun/) components in Ruby on Rails applications, reducing verbosity.\n\nIt also features caching for lookups, ensuring that it operates with minimal overhead and maximal speed.\n\n```erb\n\u003c%# Instead of: %\u003e\n\u003c%= render Admin::Dashboard::TabsComponent.new(style: :compact) do |tabs| %\u003e\n  ...\n\u003c% end %\u003e\n\n\u003c%# You can now also do: %\u003e\n\u003c%= vc.admin.dashboard.tabs(style: :compact) do |tabs| %\u003e\n  ...\n\u003c% end %\u003e\n```\n\nIt works out of the box with just a `bundle add vc_shortcut`, and is also highly customizable.\n\nBy default, two shortcuts are set up: `vc` for rendering and `vci` for instantiating components. You can change the shortcut prefix.\n\nFor more advanced use-cases, it also allows you to change the lookup logic as well as setup custom shortcuts.\n\n## Installation\n\nAdd `vc_shortcut` to your Gemfile:\n\n```shell\nbundle add vc_shortcut\n```\n\n## Usage\n\nIf you're using ViewComponent or Phlex in your Rails app and your component class names end with `Component` or `::Component` (which should be the standard), there's nothing else you need to do.\n\nBy default, two shortcuts are set up: `vc` for rendering and `vci` for instantiating components.\n\nYou can start using these helpers from any views or from your components.\n\n#### Example:\n\n```ruby\n### Instead of:\nrender Wysiwyg::UploadFieldComponent.new(limit: 50.megabytes) do |upload_field|\n  upload_field.with_footer do\n      render IconComponent.new('file')\n  end\nend\n### You can now also do:\nvc.wysiwyg.upload_field(limit: 50.megabytes) do |upload_field|\n  upload_field.with_footer do\n    vc.icon('file')\n  end\nend\n\n### Instead of:\ninstance = ProgressBarComponent.new(progress: 75)\n### You can now also do:\ninstance = vci.progress_bar(progress: 75)\n```\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n## Interested in a powerful Rails UI library?\n\nI am working on a super-powerful Rails UI library - components as well as templates \u0026 patterns.\n\n[Please check this out if you're interested](https://owaiskhan.me/rails-ui-library).\n\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n## Advanced\n\nYou can customize things by creating an initializer file at `config/initializers/vc_shortcut.rb`.\n\n#### Customize name of default shortcuts\n\nYou can rename the default shortcuts or disable them entirely:\n\n```ruby\n# In config/initializers/vc_shortcut.rb:\nVcShortcut.render_shortcut      = :vc  # Or whatever you prefer\nVcShortcut.instantiate_shortcut = :vci # Or whatever you prefer\n```\n\nYou can disable a shortcut by setting its value to `false`.\n\n#### Custom Component Lookup\n\nBy default, we assume your component class names end with `Component` or `::Component`, which is the standard and should cover the majority of cases.\n\nHowever, if you're doing something non-standard, you can customize the logic that finds a component:\n\n```ruby\n# In config/initializers/vc_shortcut.rb:\nVcShortcut.find_component = -\u003e(camelized_name) {\n  \"#{camelized_name}Component\".safe_constantize || \"#{camelized_name}::Component\".safe_constantize\n}\n```\n\nFor example, if all your components are namespaced under `Polaris` and are suffixed with `Primitive` instead of `Component`, you can set:\n```ruby\n# In config/initializers/vc_shortcut.rb:\nVcShortcut.find_component = -\u003e(camelized_name) {\n  \"Polaris::#{camelized_name}Primitive\".safe_constantize\n}\n## So instead of:\n#   `render Polaris::Admin::NavbarPrimitive.new`\n#  You can now also do:\n#   `vc.admin.navbar`\n```\n\n## Super Advanced\n\nYou can take customization one level further if needed:\n\n#### Registering Additional Custom Shortcuts\n\n```ruby\n# In config/initializers/vc_shortcut.rb:\nVcShortcut.register :admin,\n  find_component: -\u003e(camelized_name) {\n    \"Ui::Admin::#{camelized_name}::Component\".safe_constantize\n  },\n  process: -\u003e(context) {\n    context.view_context.render(\n      context.component.new(*context.call_args, **context.call_kwargs),\n      \u0026context.call_block\n    )\n  }\n## So instead of:\n#   `render Ui::Admin::Navbar::Component.new`\n#  You can now also do:\n#   `admin.navbar`\n```\n\n#### Taking Full Control\n\nYou can customize the find process even more by specifying `find` instead of `find_component`:\n\n```ruby\n# In config/initializers/vc_shortcut.rb:\nVcShortcut.register :admin,\n  find: -\u003e(context) {\n    # If you return :has_more, we'll assume there's another component coming up in the chain.\n    # If you return a non-nil value, we'll assume this is the leaf component and move on to call `process`.\n    # If you return nil, we'll assume nothing was found for the given chain and raise an error.\n    chain_camelized = context.chain_camelized\n    component = \"Ui::#{chain_camelized}::Component\".safe_constantize\n    next component if component\n    :has_more if chain_camelized.safe_constantize\n  },\n  process: -\u003e(context) {\n    context.view_context.render(\n      context.component.new(*context.call_args, **context.call_kwargs),\n      \u0026context.call_block\n    )\n  }\n## So instead of:\n#   `render Ui::Admin::Navbar::Component.new`\n#  You can now also do:\n#   `admin.navbar`\n```\n\nThe return value of the `register` call is a module that you can include in places where you wish to make the helper available. It's, however, automatically included for all your views, view components, and phlex components.\n\n#### What is `context` in the above examples?\n\n`context` is provided to the `find` and `process` proc. It's an object that responds to the following methods:\n\n##### 1. `context.chain`:\nChain until now. E.g., if you call `vc.admin.button`:\n* When processing :admin, chain will be [:admin].\n* Then, when processing :button, chain will be [:admin, :button].\n\n##### 2. `context.chain_camelized`:\nJust does `context.chain.join('/').camelize`. So, if chain was [:admin, :buttton], it'd return `Admin::Button`.\n\n##### 3. `context.component`:\nOnly set when called in the `process` proc. It is the component returned by the `find` or `find_component` proc.\n\n##### 4. `context.call_args` `context.call_kwargs`, `context.call_block`:\nOnly set when called in the `process` proc. These are the arguments used when calling the shortcut. E.g.:\n```ruby\nvc.admin.navbar('Treact', size: :sm, style: :compact) do |navbar|\n  navbar.with_menu_item(...)\nend\n```\nHere, `context.call_args` will be `['Treact']`, `context.call_kwargs` will be `{ size: :sm, style: :compact }` and `context.call_block` will be the block above.\n\n##### 5. `context.view_context`:\n\nThe view context when the shortcut was called. You can use it to render the component. E.g.:\n\n```ruby\ninstance = context.component.new(*context.call_args, **context.call_kwargs)\nhtml = context.view_context.render(instance, \u0026context.call_block)\n```\n\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub.\n\n## License\n\nThe gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowaiswiz%2Fvc_shortcut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowaiswiz%2Fvc_shortcut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowaiswiz%2Fvc_shortcut/lists"}