{"id":22954965,"url":"https://github.com/e-contract/jsf-crud","last_synced_at":"2025-08-13T02:32:15.009Z","repository":{"id":45120500,"uuid":"255851969","full_name":"e-Contract/jsf-crud","owner":"e-Contract","description":null,"archived":false,"fork":false,"pushed_at":"2023-02-22T08:28:25.000Z","size":503,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-02-26T04:52:23.833Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e-Contract.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-15T08:23:36.000Z","updated_at":"2022-10-10T22:21:05.000Z","dependencies_parsed_at":"2022-09-02T22:32:09.196Z","dependency_job_id":null,"html_url":"https://github.com/e-Contract/jsf-crud","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-Contract%2Fjsf-crud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-Contract%2Fjsf-crud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-Contract%2Fjsf-crud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-Contract%2Fjsf-crud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e-Contract","download_url":"https://codeload.github.com/e-Contract/jsf-crud/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229724862,"owners_count":18114518,"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":[],"created_at":"2024-12-14T16:20:13.442Z","updated_at":"2024-12-14T16:20:14.133Z","avatar_url":"https://github.com/e-Contract.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"JSF CRUD Project\n================\n\nThe JSF CRUD Project delivers a JSF component, based on PrimeFaces, to perform simple CRUD operations on JPA entities.\nThe JSF CRUD component is a perfect match for the construction of administrator portals where you basically want simple and fast CRUD operations on the JPA entities within your Java EE application.\n\nThe component has been tested on the following application servers:\n* JBoss EAP 6.4.22\n* JBoss EAP 7.4.0\n* WildFly 19.1.0\n* Payara 5.201\n* Oracle WebLogic Server 14.1.1\n* Apache TomEE 8.0.1\n* Open Liberty 20.0.0.5\n\nThe component has been tested with PrimeFaces versions:\n* 11.0.0\n\n\n# Usage\n\nIf you are using Maven, refer to the e-contract.be Maven repository via:\n```xml\n\u003crepository\u003e\n    \u003cid\u003ee-contract\u003c/id\u003e\n    \u003curl\u003ehttps://www.e-contract.be/maven2/\u003c/url\u003e\n    \u003creleases\u003e\n        \u003cenabled\u003etrue\u003c/enabled\u003e\n    \u003c/releases\u003e\n\u003c/repository\u003e\n```\nInclude the `jsf-crud-lib` JSF library within your WAR (JPA, CDI, BV, and JSF enabled) as follows:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ebe.e-contract.jsf-crud\u003c/groupId\u003e\n    \u003cartifactId\u003ejsf-crud-lib\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nWithin a JSF page you can now add the following:\n```xml\nxmlns:crud=\"urn:be:e-contract:crud:jsf\"\n...\n\u003ccrud:crud entity=\"YourEntity\"/\u003e\n```\nIt cannot get easier than this.\n\n# Demo\n\nCheckout the source code via:\n```\ngit clone https://github.com/e-Contract/jsf-crud.git\n```\n\n## WildFly\n\nStart a WildFly via:\n```\ncd wildfly-19.1.0.Final/bin/\n./standalone.sh\n```\n\nBuild the project via Maven:\n```\ncd jsf-crud\nmvn clean install\n```\n\nDeploy the demo web application to the local running WildFly via:\n```\ncd jsf-crud-demo\nmvn wildfly:deploy\n```\n\nNavigate your web browser to:\nhttp://localhost:8080/jsf-crud-demo/\n\n\n## Payara\n\nStart Payara via:\n```\ncd payara5/bin/\n./asadmin start-domain --verbose\n```\n\nBuild the project via Maven:\n```\ncd jsf-crud\nmvn clean install\n```\n\nDeploy the demo web application to the local running Payara via:\n```\n./asadmin deploy ~/jsf-crud/jsf-crud-demo/target/jsf-crud-demo-x.y.z-SNAPSHOT.war\n```\n\nNavigate your web browser to:\nhttp://localhost:8080/jsf-crud-demo/\n\nUndeploy the demo web application via:\n```\n./asadmin undeploy jsf-crud-demo-x.y.z-SNAPSHOT\n```\n\nList all deployed applications via:\n```\n./asadmin list-applications\n```\n\n## Open Liberty\n\nBuild the project via Maven:\n```\ncd jsf-crud\nmvn clean install\n```\n\nRun the demo web application on Open Liberty via:\n```\ncd jsf-crud-demo\nmvn clean test -Pliberty\n```\n\nNavigate your web browser to:\nhttp://localhost:9080/jsf-crud-demo/\n\n# Tutorial\n\nThis tutorial gives you an overview of the most important features of the JSF CRUD component.\n\nOnce you have your JPA entity defined, you can start with the most simple construct:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"/\u003e\n```\nThis gives you a table with basic create, read, update, and delete functionality.\nThe JSF CRUD component uses reflection to construct a UI based on the JPA annotations.\n\nYou can change the displayed name of a field via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\" label=\"A human readable label\"/\u003e\n\u003c/crud:crud\u003e\n```\n\nChange the size of the field input component via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\" size=\"60\"/\u003e\n\u003c/crud:crud\u003e\n```\n\nYou can sort and filter on a field within the main table via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\" sort=\"true\" filter=\"true\"/\u003e\n\u003c/crud:crud\u003e\n```\n\nYou can hide a field from the main table, but still have it displayed via a read operation as follows:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\" hide=\"true\"/\u003e\n    \u003ccrud:read/\u003e\n\u003c/crud:crud\u003e\n```\n\nYou can change the order of the fields within the main table using:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:order\u003e\n        \u003ccrud:field name=\"firstField\"/\u003e\n        \u003ccrud:field name=\"secondField\"/\u003e\n        ...\n    \u003c/crud:order\u003e\n\u003c/crud:crud\u003e\n```\n\nIf you don't want a certain CRUD functionality, you can disable it via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:create disabled=\"true\"/\u003e\n    \u003ccrud:update disabled=\"true\"/\u003e\n    \u003ccrud:delete disabled=\"true\"/\u003e\n\u003c/crud:crud\u003e\n```\n\nIf you don't want a certain field to be visible within the update dialog, you can hide it as follows:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:update\u003e\n        \u003ccrud:field name=\"yourField\" hide=\"true\"/\u003e\n    \u003c/crud:update\u003e\n\u003c/crud:crud\u003e\n```\n\nMark a field as a password field via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\"\u003e\n        \u003ccrud:password feedback=\"true\" match=\"true\"/\u003e\n    \u003c/crud:field\u003e\n\u003c/crud:crud\u003e\n```\n\nMark a field as a binary field (with upload/download functionality) via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\"\u003e\n        \u003ccrud:binary contentType=\"text/plain\"/\u003e\n    \u003c/crud:field\u003e\n\u003c/crud:crud\u003e\n```\n\nBesides fields, you can also display properties via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:property name=\"yourProperty\"/\u003e\n\u003c/crud:crud\u003e\n```\n\nYou can also change the default input component used for a field.\nFor example, to change the input component of a field on the update dialog, you can define:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:update\u003e\n        \u003ccrud:field name=\"yourField\"\u003e\n            \u003cf:facet name=\"input\"\u003e\n                \u003cp:spinner/\u003e\n            \u003c/f:facet\u003e\n        \u003c/crud:field\u003e\n    \u003c/crud:update\u003e\n\u003c/crud:crud\u003e\n```\nSimilarly, you can change the output component of a field within the main table via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\"\u003e\n        \u003cf:facet name=\"output\"\u003e\n            \u003ch:outputText/\u003e\n        \u003c/f:facet\u003e\n    \u003c/crud:field\u003e\n\u003c/crud:crud\u003e\n```\n\n## Custom Actions\n\nBesides the CRUD operations, you can easily add custom actions via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:action value=\"Your custom action\" action=\"...\" oncomplete=\"...\" update=\"...\"/\u003e\n\u003c/crud:crud\u003e\n```\nThe `action` method expression receives the selected entity as parameter.\nThe `crud:action` component can handle various return types. For example, if the `action` method returns the entity, it will get saved in the database.\n\nIf your custom action opens a dialog (via `oncomplete=\"PF('yourDialog').show()\"`), you can access the currently selected entity within the dialog as follows:\n```xml\n\u003ccrud:entity var=\"entity\"\u003e\n    \u003ch:outputText value=\"#{entity.yourField}\"/\u003e\n\u003c/crud:entity\u003e\n```\n\nWithin your dialogs, you can save the selected entity via:\n```xml\n\u003ccrud:entity var=\"entity\"\u003e\n    ...\n    \u003ccrud:saveButton value=\"Your Action\" action=\"#{yourController.yourAction}\"/\u003e\n\u003c/crud:entity\u003e\n```\nWhere the `action` method expression can make the entity to get saved within the database by simply returning it.\n\nTo mark an action as a download, you use:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:action value=\"Download something\"\u003e\n        \u003ccrud:fileDownload value=#{yourController.yourMethodWithEntityParameterAndStreamedContentReturnType}\u003e\n    \u003c/crud:action\u003e\n\u003c/crud:crud\u003e\n```\n\nYou can even let the JSF CRUD component create a dialog for your custom action itself via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:action value=\"Custom Action\"\u003e\n        \u003cf:facet name=\"dialog\"\u003e\n            \u003ch:form\u003e\n                \u003ccrud:entity var=\"entity\"\u003e\n                    ...\n                \u003c/crud:entity\u003e\n                ...\n            \u003c/h:form\u003e\n        \u003c/f:facet\u003e\n    \u003c/crud:action\u003e\n\u003c/crud:crud\u003e\n```\n\nBesides custom row actions, you can also define custom global actions that will be visible within the main table footer as follows:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:globalAction value=\"Your custom global action\" action=\"...\" oncomplete=\"...\" update=\"...\"/\u003e\n\u003c/crud:crud\u003e\n```\n\nDefine a global download action as follows:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:globalAction value=\"Download something\"\u003e\n        \u003ccrud:fileDownload value=#{yourController.yourMethodWithStreamedContentReturnType}\u003e\n    \u003c/crud:globalAction\u003e\n\u003c/crud:crud\u003e\n```\n\n## Events\n\nYou can define listeners for different CRUD events:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:createListener action=\"#{yourController.createdEventHandler}\"/\u003e\n    \u003ccrud:updateListener action=\"#{yourController.updatedEventHandler}\"/\u003e\n    \u003ccrud:deleteListener action=\"#{yourController.deletedEventHandler}\"/\u003e\n\u003c/crud:crud\u003e\n```\nwhere you have the following event listeners defined in you backing bean:\n```java\npublic void createdEventHandler(CreateEvent createEvent) {\n    // do something after the entity has been created\n}\n\npublic void updatedEventHandler(UpdateEvent updateEvent) {\n    // do something after the entity has been updated\n}\n\npublic void deletedEventHandler(DeleteEvent deleteEvent) {\n    // do something after the entity has been deleted\n}\n```\n\nThe JSF CRUD component also fires CDI events, which you can observe as follows:\n```java\npublic void handlePreCreateEvent(@Observes @HandlesEntity(YourEntity.class) PreCreateEvent preCreateEvent) {\n    // do something before the entity is created\n}\n\npublic void handlePreUpdateEvent(@Observes @HandlesEntity(YourEntity.class) PreUpdateEvent preUpdateEvent) {\n    // do something before the entity is updated\n}\n\npublic void handlePreDeleteEvent(@Observes @HandlesEntity(YourEntity.class) PreDeleteEvent preDeleteEvent) {\n    // do something before the entity is deleted\n}\n```\n\n## Security\n\nBecause the JSF CRUD component directly performs JPA operations, we might lose the RBAC security features normally provided by the CDI/EJB backing beans. To compensate for this, the JSF CRUD component can be directed to perform RBAC security verifications as follows:\n```xml\n\u003ccrud:crud entity=\"YourEntity\" roleAllowed=\"administrator\"/\u003e\n```\n\nThis can even be configured globally via the following `web.xml` context parameter:\n```xml\n\u003ccontext-param\u003e\n    \u003cparam-name\u003ecrud.roleAllowed\u003c/param-name\u003e\n    \u003cparam-value\u003eadministrator\u003c/param-value\u003e\n\u003c/context-param\u003e\n```\n\n## Custom Query\n\nPer default the JSF CRUD component will display all your entities within the main table.\nYou can customize this main query via:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:query query=\"SELECT e FROM YourEntity AS e WHERE e.yourField = :yourParam\"\u003e\n        \u003ccrud:queryParameter name=\"yourParam\" value=\"#{...}\"/\u003e\n    \u003c/crud:query\u003e\n\u003c/crud:crud\u003e\n```\n\n## Relationships\n\nThe JSF CRUD component can handle various types of JPA relationships.\n`@ManyToOne` and `@OneToOne` relationships are editable via a `SelectOneMenu` JSF component.\n`@OneToMany` and `@ManyToMany` relationships are editable via a `SelectManyMenu` JSF component.\n\nFor `@OneToMany` relationships the available options are automatically limited to prevent transactions errors for entities that are not on the owning side of the relationships.\n\nIt is possible to override the default available selection list on a relationship field using a custom field query as follows:\n```xml\n\u003ccrud:crud entity=\"YourEntity\"\u003e\n    \u003ccrud:field name=\"yourField\"\u003e\n        \u003ccrud:query query=\"SELECT e FROM OtherEntity AS e WHERE ...\"/\u003e\n    \u003c/crud:field\u003e\n\u003c/crud:crud\u003e\n```\n\nThe entities on the other side of a relationship are also visualized in a smart way. If the entity implements its own `toString` method, this method is being used. If not, the entity is visualized based on its primary key.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe-contract%2Fjsf-crud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe-contract%2Fjsf-crud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe-contract%2Fjsf-crud/lists"}