Compare commits

..
3 Commits
7 changed files with 368 additions and 189 deletions

No files matched your search

+10 -53
View File
@@ -1,57 +1,14 @@
version: 2.1
setup: true
orbs:
qqq-orb: kingsrook/qqq-orb@0.5.0
qqq-orb: kingsrook/qqq-orb@0.7.15
workflows:
test_only:
setup:
jobs:
- qqq-orb/mvn_test_only:
context: [ qqq-maven-registry-credentials ]
filters:
branches:
ignore: /(develop|main|release/.*|hotfix/.*|integration.*)/
tags:
only: []
publish_snapshot:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: snapshot
filters:
branches:
only:
- develop
publish_release_candidate:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: release_candidate
filters:
branches:
only:
- /release\/.*/
publish_release:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: release
filters:
branches:
only: [ main ]
tags:
only: [ /v.*/ ]
publish_hotfix_release:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: hotfix
filters:
branches:
only:
- /hotfix\/.*/
- qqq-orb/generate_pipeline:
orb_version: 0.7.15
filters:
branches:
ignore: automation/qbit-rc-pending
tags:
only: /v.*/
-31
View File
@@ -1,31 +0,0 @@
# GitHub Release Configuration
# Auto-generates release notes from PR labels
changelog:
exclude:
labels:
- ignore-for-release
- duplicate
- invalid
authors:
- dependabot
- dependabot[bot]
categories:
- title: Breaking Changes
labels:
- breaking-change
- breaking
- title: New Features
labels:
- enhancement
- feature
- title: Bug Fixes
labels:
- bug
- fix
- title: Dependencies
labels:
- dependencies
- title: Other Changes
labels:
- "*"
+23
View File
@@ -0,0 +1,23 @@
name: CodeQL
'on':
push:
branches:
- main
- develop
- release/**
- hotfix/**
pull_request: {}
schedule:
- cron: 41 16 * * 0
workflow_dispatch: {}
permissions:
contents: read
actions: read
security-events: write
packages: read
concurrency:
group: codeql-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
analyze:
uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22
+74
View File
@@ -0,0 +1,74 @@
name: Release candidate
'on':
workflow_dispatch:
inputs:
dry_run:
description: Plan a cut without changing release state
type: boolean
default: false
finalize:
description: Retry finalization of an existing cut; do not cut another RC
type: boolean
default: false
recover:
description: Recover the same published RC after a deployment timeout; never
reupload
type: boolean
default: false
circle_build:
description: Original Circle publisher build number (recovery only)
type: string
default: ''
merge_sha:
description: Existing cut merge_sha (finalize retry only)
type: string
default: ''
bump_sha:
description: Existing cut bump_sha (finalize retry only)
type: string
default: ''
branch:
description: Existing cut branch (finalize retry only)
type: string
default: ''
version:
description: Existing cut version (finalize retry only)
type: string
default: ''
pull_request:
types:
- closed
branches:
- develop
repository_dispatch:
types:
- qbit-rc-published
permissions:
contents: write
actions: read
checks: read
jobs:
release-rc:
if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
|| (github.event_name == 'pull_request' && github.event.pull_request.merged
== true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
'release:rc'))
uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
with:
dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
}}
finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
== 'workflow_dispatch' && inputs.finalize) }}
recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
}}
circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
|| '' }}
merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
|| inputs.merge_sha || '' }}
bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
|| inputs.bump_sha || '' }}
branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
|| inputs.branch || '' }}
version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
|| inputs.version || '' }}
secrets: inherit
+16
View File
@@ -0,0 +1,16 @@
profile: qbit
orb_version: 0.7.15
default_branch: develop
java_version: '21'
browsers: true
api_checks: false
docs_only: false
release_on_main: true
release_tag_policy: v-prefix
test_branch_policy: feature-no-hotfix
publish:
snapshot: true
release_candidate: true
release: true
hotfix: true
asciidoc: false
+243 -103
View File
@@ -1,150 +1,290 @@
# qbit-customizable-table-views
# QBit: Customizable Table Views
User-defined saved views for QQQ dashboard tables.
[![Build Status](https://circleci.com/gh/Kingsrook/qbit-customizable-table-views.svg?style=svg)](https://circleci.com/gh/Kingsrook/qbit-customizable-table-views)
[![Maven Central](https://img.shields.io/maven-central/v/com.kingsrook.qbits/qbit-customizable-table-views.svg)](https://central.sonatype.com/namespace/com.kingsrook.qbits)
[![Java](https://img.shields.io/badge/java-17+-blue.svg)](https://adoptium.net/)
[![License](https://img.shields.io/badge/license-AGPL%203.0-green.svg)](LICENSE.txt)
**For:** QQQ developers who want users to save and share custom table configurations
**Status:** Stable
**QBit Customizable Table Views** provides table personalization capabilities for QQQ applications, allowing users to customize which fields and widgets they see based on their roles and permissions.
## Why This Exists
## 🚀 What Makes This QBit Different?
Different users need different views of the same data. Sales wants to see orders by region. Operations wants orders by status. Each applies different filters, sorts columns differently, and hides irrelevant fields.
**Role-Based Table Customization** - This QBit enables fine-grained control over table presentation without modifying application code. Users see different fields and widgets based on their assigned roles, providing a personalized experience while maintaining security and data integrity.
This QBit lets users save these configurations as named views. Create a view, adjust columns and filters, save it, and switch between views instantly. Views can be private or shared with the team.
## 🔓 Open Source & Full Control
## Features
**This QBit is 100% open source** - you have complete ownership and control:
- **Saved Views** - Store filter, sort, and column configurations
- **Column Visibility** - Show/hide columns per view
- **Column Order** - Reorder columns with drag-and-drop
- **Filter Presets** - Save complex filter combinations
- **View Sharing** - Share views with roles or all users
- **Default Views** - Set a view as the default for a table
- **💻 Your Code**: Full access to the QBit's source code
- **🗄️ Your Data**: All customization data stays in your systems
- **🏗️ Your System**: Deploy anywhere - on-premises, cloud, or hybrid
- **🔒 No Vendor Lock-in**: No SaaS subscriptions, no proprietary dependencies
- **⚡ Full Customization**: Modify, extend, and adapt the QBit to your exact needs
- **🌍 Community Driven**: Built by engineers, for engineers
## Quick Start
### ✨ Core Capabilities
- **🎯 Table Personalization**: Customize field visibility and widget access per user role
- **🔐 Role-Based Access**: Control table views through user role assignments
- **⚙️ Flexible Configuration**: Set up customizations before activation
- **🔄 Dynamic Merging**: Combine multiple table views using least-restrictive rules
- **📊 Access Level Management**: Control field access (Hidden, Read-only, Required, Optional)
## 🏗️ Architecture
This QBit implements QQQ's `TableMetaDataPersonalizerInterface` to provide table customization capabilities:
```mermaid
graph LR
subgraph "Application Layer"
A[QQQ Application<br/>Tables & Widgets]
end
subgraph "QBit Layer"
B[CustomizableTableViewsQBit<br/>TableMetaDataPersonalizerInterface]
C[CustomizableTable<br/>TableView<br/>TableViewField<br/>TableViewWidget]
end
subgraph "User Layer"
D[User Roles<br/>TableViewRoleInt]
end
A <--> B
B <--> C
C <--> D
```
### Technology Stack
- **Java**: Java 17+ with UTF-8 encoding
- **QQQ Framework**: Built on QQQ's metadata-driven architecture
- **Maven**: Standard Maven build system
- **Role Management**: Integrates with QQQ's role and permission system
## 🚀 Quick Start
### Prerequisites
- **Java 17+** (required for QQQ features)
- **Maven 3.8+** (for build system)
- **QQQ Framework** (parent framework)
- QQQ application (v0.20+)
- QQQ dashboard deployed
- Database backend configured
### Build Locally
```bash
# Clone the repository
git clone git@github.com:Kingsrook/qbit-customizable-table-views.git
cd qbit-customizable-table-views
### Installation
Add to your `pom.xml`:
# Build the QBit
mvn clean install
```
### Use in Your Project
```xml
<dependency>
<groupId>io.qrun</groupId>
<groupId>com.kingsrook.qbits</groupId>
<artifactId>qbit-customizable-table-views</artifactId>
<version>0.2.0</version>
<version>...</version>
</dependency>
```
### Register the QBit
## 📚 Documentation
```java
public class AppMetaProvider extends QMetaProvider {
@Override
public void configure(QInstance qInstance) {
new CustomizableTableViewsQBit().configure(qInstance);
}
}
**📖 [Complete Documentation Wiki](https://github.com/Kingsrook/qqq/wiki)** - Start here for comprehensive guides
- **[🏠 Home](https://github.com/Kingsrook/qqq/wiki/Home)** - Project overview and quick start
- **[🏗️ Architecture](https://github.com/Kingsrook/qqq/wiki/High-Level-Architecture)** - System design and principles
- **[🔧 Development](https://github.com/Kingsrook/qqq/wiki/Developer-Onboarding)** - Setup and contribution guide
- **[📦 QBits](https://github.com/Kingsrook/qqq/wiki/QBit-Development)** - QBit development guide
- **[🚀 Building](https://github.com/Kingsrook/qqq/wiki/Building-Locally)** - Local development workflow
## 🤝 Contributing
This QBit is **open source** and welcomes contributions!
- **🐛 [Report Issues](https://github.com/Kingsrook/qqq/issues)** - Bug reports and feature requests
- **📝 [Contribution Guide](https://github.com/Kingsrook/qqq/wiki/Contribution-Guidelines)** - How to contribute code and documentation
- **🔍 [Code Standards](https://github.com/Kingsrook/qqq/wiki/Code-Review-Standards)** - QQQ's coding standards and review process
**First time contributing?** Start with our [Developer Onboarding Guide](https://github.com/Kingsrook/qqq/wiki/Developer-Onboarding) to get your environment set up.
## 🏢 About Kingsrook
This QBit is built by **[Kingsrook](https://qrun.io)** - making engineers more productive through intelligent automation and developer tools.
- **Website**: [https://qrun.io](https://qrun.io)
- **Contact**: [contact@kingsrook.com](mailto:contact@kingsrook.com)
- **GitHub**: [https://github.com/Kingsrook](https://github.com/Kingsrook)
## 📄 License
This project is licensed under the **GNU Affero General Public License v3.0** - see the [LICENSE.txt](LICENSE.txt) file for details.
---
## 📖 Detailed Usage Guide
### Overview
*Note: This is one of the original QBit implementations - so, some of the mechanics of how
it is loaded and used by an application are not exactly fully defined at the time of its
creation... Please excuse any dust or not-quite-round wheels you find here!*
This QBit provides an implementation of QQQ's `TableMetaDataPersonalizerInterface` along with
management tables for the same.
The idea behind this model for table personalization (aka customization) is as follows:
* By default, no tables in the app are customized.
* This means that all users can see all fields and widgets, as the table is defined in the application code.
* For a table to be customized, a record for it must exist in the **Customizable Table** table.
* Custom views of a table will not actually apply to users in the application until the **Customizable Table** record
for the table has its **Is Active** field set to true. The idea being, that you can set up custom views for a table
before they are activated and applied to users.
* Setting up a customized table consists of building one or more **Table View** records. A Table View is a
definition of how the table should be presented to a user (e.g., which fields and widgets they will have access to).
each table view record consists of:
* The table that the view applies to.
* A list of **Fields** from the table along with an **Access Level** for the field. See below for additional
details on access levels.
* A list of **Widgets** from that table.
* Table Views are assigned to users via user roles, by building records in the **Table View Role Int** (intersection)
table.
* In addition, a **Default Table View** can optionally be set in the **Customizable Table** record for a table.
#### Applying Customization
* When a table is customized (e.g., its Customizable Table record's Is Active field is true):
* All non-required fields are removed from the table for all users. In other words, the only fields left in the table
are any fields marked in the application code as required (plus the table's primary key / id). Also, all widgets
are removed from the table.
* From this base set of required fields and zero widgets, all Table Views that are assigned to the user (via their
roles) are merged together to define the set of fields and widgets that the user can see.
* If a user does not have access to any Table Views via their roles, but the table does have a Default Table View,
then that is the only Table View that is available to the user.
#### Field Access Level Rules
* Fields in tables can generally have 4 levels of pre-defined access, coded into the application:
* **Hidden** - the field is not visible to any user. It only exists for the system to use, but not for users to see.
* **Read-only** - the field is visible, but users cannot edit its value. ex. *Create Date*, *Id*
* **Required** - the field is visible and editable, and all records MUST have a value. ex. *Name* (on several tables
that are uniquely identified by Name)
* **Optional** - the field is visible and editable, and records may or may not have a value. ex. *Description* or
*Ship To Address 2*.
* In a custom Table View, at a basic level, you are defining what fields should be available to a user. However,
there is a limited set of adjustments you can make to the access level for fields. Specifically, Optional fields
can be changed to be Read-Only or Required.
* Furthermore, when multiple Table Views are being merged together (e.g., because a user has multiple roles each of
which have a Table View associated with them), the logic of what Access Rules applies is generally referred to as
"least-restrictive rule wins".
* For example, a field being Optional is a lesser restriction than a field being Required, so if one Table View
has a field marked as Optional, and another has it as Required, then the result is that the field will be Optional.
* The full set of combinations of access levels and their resulting output is:
```
Hidden + Read-only = Read-only
Hidden + Required = Required
Hidden + Optional = Optional
Read-only + Required = Required
Read-only + Optional = Optional
Required + Optional = Optional
```
### Enable for Tables
### Usage
```java
new QTableMetaData()
.withName("order")
.withCustomViewsEnabled(true);
#### Pom dependency
```xml
<dependency>
<groupId>com.kingsrook.qbits</groupId>
<artifactId>qbit-customizable-table-views</artifactId>
<version>...</version>
</dependency>
```
## Usage
### Dashboard Experience
Users interact with views through the dashboard:
1. Navigate to a table
2. Adjust columns, filters, and sorting
3. Click "Save View"
4. Name the view and set visibility (private/shared)
5. Switch views from the dropdown
### Programmatic View Creation
#### Setup
```java
new QSavedViewMetaData()
.withName("pendingOrders")
.withTable("order")
.withLabel("Pending Orders")
.withFilter(new QQueryFilter()
.withCriteria("status", Operator.EQUALS, "pending"))
.withColumns("orderNumber", "customerName", "total", "createdDate")
.withSortBy("createdDate", SortOrder.DESC)
.withSharedWithRoles("sales", "operations");
// configure the qbit:
CustomizableTableViewsQBitConfig config = new CustomizableTableViewsQBitConfig()
// if any table customizations are required:
.withTableMetaDataCustomizer(tableMetaDataCustomizer);
// create a qbit producer and produce all of the qbit's meta data
CustomizableTableViewsQBitProducer producer = new CustomizableTableViewsQBitProducer().withQBitConfig(config);
MetaDataProducerMultiOutput allQBitMetaData = producer.produce(qInstance);
// register the table meta data personlizer
CustomizableTableViewsQBitProducer.activateTableMetaDataPersonalizerInterface(qInstance);
// either return allQBitMetaData from a MetaDataProducerInterface, or
// call: allQBitMetaData.addSelfToInstance(qInstance);
```
### Default Views
### Provides
#### Tables
* **CustomizableTable** - marks a table as being eligible for customization (building TableView records), and controls if
customizations are actually active for users in the application or not.
* **TableView** - a set of fields and widgets to apply to a CustomizableTable.
* **TableViewField** - a single field with access level that is part of a TableView
* **TableViewWidget** - a single widget that is part of a TableView
* **TableViewRoleInt** - intersection record between TableView and Role.
Set a view as the default for all users or specific roles:
#### Classes
The key business logic of this QBit is provided by `CustomizableTableViewsTablePersonalizer` which implements
`TableMetaDataPersonalizerInterface`, and applies the table personalization logic to tables in the application,
based on data in the tables.
This class needs to be registered in a QInstance as a supplemental code reference, which can be done by:
`CustomizableTableViewsQBitProducer.activateTableMetaDataPersonalizerInterface(qInstance);`
### Dependencies
#### Roles
* `CustomizableTableViewsTablePersonalizer` depends on a user's session having an entry in its values map called
`"roleIds"`. This value is expected to be a comma-delimited list of role ids assigned to the user.
* You may need to set this value in the session yourself, in an implementation of
`QAuthenticationModuleCustomizerInterface` in the `finalCustomizeSession` method, such as:
```java
new QSavedViewMetaData()
.withName("activeCustomers")
.withTable("customer")
.withIsDefault(true)
.withFilter(new QQueryFilter()
.withCriteria("status", Operator.EQUALS, "active"));
Set<Integer> roleIds = PermissionManager.getInstance().getRoleIdsForUser(userId);
qSession.setValue("roleIds", StringUtils.join(",", roleIds));
```
* The `TableViewRoleInt` table's `roleId` field is set with `possibleValueSourceName = "role"`. This table and PVS
can be provided by `qbit-user-role-permission`, or, any application-defined role table.
### View Inheritance
## 🆘 Support & Community
Create views that extend others:
### ⚠️ Important: Use Main QQQ Repository
```java
new QSavedViewMetaData()
.withName("myPendingOrders")
.withExtendsView("pendingOrders")
.withAdditionalFilter(new QQueryFilter()
.withCriteria("assignedToUserId", Operator.EQUALS, "${currentUserId}"));
```
**All support, issues, discussions, and community interactions should go through the main QQQ repository:**
## Configuration
- **Main Repository**: https://github.com/Kingsrook/qqq
- **Issues**: https://github.com/Kingsrook/qqq/issues
- **Discussions**: https://github.com/Kingsrook/qqq/discussions
- **Wiki**: https://github.com/Kingsrook/qqq.wiki
The QBit creates these tables:
### Why This Repository Exists
| Table | Purpose |
|-------|---------|
| `saved_view` | View definitions |
| `saved_view_column` | Column configurations |
| `saved_view_share` | Sharing permissions |
This repository is maintained separately from the main QQQ repository to:
- **Enable independent QBit development** and versioning
- **Allow QBit-specific CI/CD** and deployment pipelines
- **Provide clear separation** between QBit functionality and core framework concerns
- **Support different release cycles** for QBits vs. core framework
### View Limits
### Getting Help
```java
new CustomizableTableViewsQBit()
.withMaxViewsPerUser(50)
.withMaxSharedViewsPerTable(20);
```
- **Documentation**: Check the [QQQ Wiki](https://github.com/Kingsrook/qqq.wiki)
- **Issues**: Report bugs and feature requests on [Main QQQ Issues](https://github.com/Kingsrook/qqq/issues)
- **Discussions**: Join community discussions on [Main QQQ Discussions](https://github.com/Kingsrook/qqq/discussions)
- **Questions**: Ask questions in the main QQQ repository
## Project Status
### Contact Information
Stable and production-ready.
- **Company**: Kingsrook, LLC
- **Email**: contact@kingsrook.com
- **Website**: https://kingsrook.com
- **Main GitHub**: https://github.com/Kingsrook/qqq
### Roadmap
## 🙏 Acknowledgments
- View folders/categories
- View usage analytics
- Export/import view configurations
- **QQQ Framework Team**: For the underlying low-code platform
- **QBit Development Team**: For the customizable table views implementation
- **Open Source Community**: For the tools and libraries that make this possible
## Contributing
---
1. Fork the repository
2. Create a feature branch
3. Run tests: `mvn clean verify`
4. Submit a pull request
**Built with ❤️ by the Kingsrook Team**
## License
Proprietary - QRun.IO
**This is a QBit component of the QQQ framework. For complete information, support, and community, visit: https://github.com/Kingsrook/qqq**
+2 -2
View File
@@ -26,7 +26,7 @@
<parent>
<groupId>com.kingsrook</groupId>
<artifactId>qbit-build-parent</artifactId>
<version>1.5.1</version>
<version>1.1.0</version>
</parent>
<groupId>com.kingsrook.qbits</groupId>
@@ -64,7 +64,7 @@
</scm>
<properties>
<revision>0.3.0-SNAPSHOT</revision>
<revision>0.2.2</revision>
</properties>