Initial Commit
This commit is contained in:
Andy Dixon
@@ -0,0 +1,314 @@
|
||||
# Greasemonkey Browser Extension
|
||||
|
||||
**Author:** Andy Dixon
|
||||
**Version:** 1.0.0
|
||||
|
||||
A powerful browser extension that allows you to execute custom JavaScript and CSS on web pages based on flexible matching conditions.
|
||||
|
||||
## Features
|
||||
|
||||
- 🎯 **Flexible Matching**: Execute scripts when:
|
||||
- A URL contains a specific string
|
||||
- A page contains a specific element (CSS selector)
|
||||
- Both conditions are met simultaneously
|
||||
|
||||
- 🎨 **Bootstrap Dark UI**: Intuitive configuration interface with Bootstrap 5 dark theme
|
||||
- 💾 **Persistent Storage**: All rules are saved and synced across your browser sessions
|
||||
- ⚡ **Multiple Rules**: Add, edit, and manage unlimited custom rules
|
||||
- 🔄 **Toggle Controls**: Easily enable/disable individual rules
|
||||
- 📝 **JavaScript & CSS**: Support for both JavaScript execution and CSS injection
|
||||
- 🔍 **Visual Indicators**: Clear badges showing rule type (URL/Element/Both) and code types (JS/CSS)
|
||||
|
||||
## Installation
|
||||
|
||||
### Chrome Installation
|
||||
|
||||
1. Navigate to the `chrome` directory
|
||||
2. Open Chrome and go to `chrome://extensions/`
|
||||
3. Enable "Developer mode" (toggle in top-right corner)
|
||||
4. Click "Load unpacked"
|
||||
5. Select the `chrome` directory
|
||||
6. The Greasemonkey extension is now installed!
|
||||
|
||||
### Firefox Installation
|
||||
|
||||
1. Navigate to the `firefox` directory
|
||||
2. Open Firefox and go to `about:debugging#/runtime/this-firefox`
|
||||
3. Click "Load Temporary Add-on"
|
||||
4. Select the `manifest.json` file from the `firefox` directory
|
||||
5. The Greasemonkey extension is now installed!
|
||||
|
||||
**Note:** For permanent Firefox installation, you'll need to sign the extension through [addons.mozilla.org](https://addons.mozilla.org).
|
||||
|
||||
## Usage
|
||||
|
||||
### Creating a Rule
|
||||
|
||||
1. Click the Greasemonkey icon in your browser toolbar
|
||||
2. Click the "+ Add Rule" button
|
||||
3. Fill in the rule details:
|
||||
- **Rule Name**: A descriptive name for your rule
|
||||
- **Match Type**: Choose how the rule should be triggered
|
||||
- *URL contains string*: Matches if URL contains the pattern
|
||||
- *Page contains element*: Matches if element selector exists
|
||||
- *Both URL and element*: Requires both conditions
|
||||
- **URL Pattern**: The string to match in the URL (e.g., `github.com`, `/search?`)
|
||||
- **Element Selector**: CSS selector to match (e.g., `#my-element`, `.my-class`, `div[data-id="123"]`)
|
||||
- **JavaScript Code**: Custom JavaScript to execute
|
||||
- **CSS Code**: Custom CSS to inject
|
||||
- **Enabled**: Toggle to enable/disable the rule
|
||||
4. Click "Save Rule"
|
||||
|
||||
### Editing a Rule
|
||||
|
||||
1. Open the Greasemonkey popup
|
||||
2. Click the edit button (pencil icon) on any rule card
|
||||
3. Modify the rule details
|
||||
4. Click "Save Rule"
|
||||
|
||||
### Deleting a Rule
|
||||
|
||||
1. Open the Greasemonkey popup
|
||||
2. Click the delete button (trash icon) on any rule card
|
||||
3. Confirm the deletion
|
||||
|
||||
### Toggling a Rule
|
||||
|
||||
Use the toggle switch on each rule card to quickly enable or disable rules without editing them.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Hide Ads on Specific Sites
|
||||
|
||||
**Match Type:** URL contains string
|
||||
**URL Pattern:** `example.com`
|
||||
**CSS Code:**
|
||||
```css
|
||||
.advertisement,
|
||||
.ad-banner,
|
||||
#sidebar-ads {
|
||||
display: none !important;
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: Auto-fill Forms
|
||||
|
||||
**Match Type:** Both URL and element
|
||||
**URL Pattern:** `form-site.com`
|
||||
**Element Selector:** `#login-form`
|
||||
**JavaScript Code:**
|
||||
```javascript
|
||||
document.getElementById('username').value = 'myusername';
|
||||
console.log('Auto-filled username field');
|
||||
```
|
||||
|
||||
### Example 3: Dark Mode Override
|
||||
|
||||
**Match Type:** URL contains string
|
||||
**URL Pattern:** `news-site.com`
|
||||
**CSS Code:**
|
||||
```css
|
||||
body {
|
||||
background-color: #1a1a1a !important;
|
||||
color: #e0e0e0 !important;
|
||||
}
|
||||
|
||||
a {
|
||||
color: #4a9eff !important;
|
||||
}
|
||||
```
|
||||
|
||||
### Example 4: Add Custom Features
|
||||
|
||||
**Match Type:** Element exists
|
||||
**Element Selector:** `.video-player`
|
||||
**JavaScript Code:**
|
||||
```javascript
|
||||
console.log('Video player detected!');
|
||||
|
||||
// Add a custom button
|
||||
const button = document.createElement('button');
|
||||
button.textContent = 'Custom Action';
|
||||
button.style.cssText = 'position:fixed;top:10px;right:10px;z-index:9999;';
|
||||
button.onclick = () => alert('Custom button clicked!');
|
||||
document.body.appendChild(button);
|
||||
```
|
||||
|
||||
### Example 5: Conditional Styling
|
||||
|
||||
**Match Type:** Both URL and element
|
||||
**URL Pattern:** `dashboard`
|
||||
**Element Selector:** `.data-table`
|
||||
**CSS Code:**
|
||||
```css
|
||||
.data-table {
|
||||
border: 2px solid #4CAF50;
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 4px 6px rgba(0,0,0,0.1);
|
||||
}
|
||||
|
||||
.data-table th {
|
||||
background-color: #4CAF50;
|
||||
color: white;
|
||||
}
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
greasemonkey/
|
||||
├── chrome/ # Chrome extension files
|
||||
│ ├── manifest.json # Chrome extension manifest (v3)
|
||||
│ ├── background.js # Background service worker
|
||||
│ ├── content.js # Content script (runs on pages)
|
||||
│ ├── popup.html # Extension popup UI
|
||||
│ ├── popup.css # Popup styling
|
||||
│ ├── popup.js # Popup functionality
|
||||
│ └── icon*.png # Extension icons
|
||||
├── firefox/ # Firefox extension files
|
||||
│ ├── manifest.json # Firefox extension manifest (v2)
|
||||
│ ├── background.js # Background script
|
||||
│ ├── content.js # Content script (runs on pages)
|
||||
│ ├── popup.html # Extension popup UI
|
||||
│ ├── popup.css # Popup styling
|
||||
│ ├── popup.js # Popup functionality
|
||||
│ └── icon*.png # Extension icons
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Content Script**: Runs on every page load (`document_idle`)
|
||||
2. **Rule Matching**: Checks all enabled rules against current page
|
||||
3. **Condition Evaluation**: Tests URL patterns and element selectors
|
||||
4. **Code Execution**:
|
||||
- JavaScript is injected as a script element
|
||||
- CSS is injected as a style element
|
||||
5. **Storage**: Rules are stored in browser's sync storage
|
||||
|
||||
### Storage Format
|
||||
|
||||
Rules are stored as JSON in browser sync storage:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"rules": [
|
||||
{
|
||||
"name": "Example Rule",
|
||||
"matchType": "url",
|
||||
"urlPattern": "example.com",
|
||||
"elementSelector": "",
|
||||
"javascript": "console.log('Hello');",
|
||||
"css": "body { background: red; }",
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Browser Compatibility
|
||||
|
||||
- **Chrome**: Requires Chrome 88+ (Manifest V3)
|
||||
- **Firefox**: Requires Firefox 48+ (Manifest V2)
|
||||
- **Edge**: Should work (Chromium-based, same as Chrome)
|
||||
- **Opera**: Should work (Chromium-based, same as Chrome)
|
||||
|
||||
## Building for Distribution
|
||||
|
||||
### Chrome
|
||||
|
||||
1. Ensure all files are in the `chrome` directory
|
||||
2. Go to `chrome://extensions/`
|
||||
3. Click "Pack extension"
|
||||
4. Select the `chrome` directory
|
||||
5. This creates a `.crx` file for distribution
|
||||
|
||||
### Firefox
|
||||
|
||||
1. Install `web-ext` tool: `npm install -g web-ext`
|
||||
2. Navigate to the `firefox` directory
|
||||
3. Run: `web-ext build`
|
||||
4. This creates a `.zip` file in `web-ext-artifacts/`
|
||||
5. Submit to [addons.mozilla.org](https://addons.mozilla.org) for signing
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **User Responsibility**: Be cautious with JavaScript code execution
|
||||
- **HTTPS**: Script injection works on both HTTP and HTTPS sites
|
||||
- **CSP**: Some sites with strict Content Security Policy may block injected scripts
|
||||
- **Permissions**: Extension requires broad permissions (`<all_urls>`) to work on all sites
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Rules Not Executing
|
||||
|
||||
1. **Check the browser console** for error messages (F12)
|
||||
2. **Verify the rule is enabled** (toggle switch)
|
||||
3. **Test the URL pattern** - ensure it matches the current page
|
||||
4. **Test the element selector** - open console and run `document.querySelector('your-selector')`
|
||||
5. **Reload the page** after creating/editing rules
|
||||
|
||||
### CSS Not Applying
|
||||
|
||||
- Use `!important` flag to override existing styles
|
||||
- Check for syntax errors in CSS
|
||||
- Verify the rule conditions are met
|
||||
|
||||
### JavaScript Not Running
|
||||
|
||||
- Check browser console for errors
|
||||
- Ensure JavaScript syntax is correct
|
||||
- Some sites may have strict Content Security Policies
|
||||
|
||||
### Storage Not Syncing
|
||||
|
||||
- Ensure browser sync is enabled
|
||||
- Check available storage quota
|
||||
- For Firefox temporary add-ons, sync storage may not persist
|
||||
|
||||
## Development
|
||||
|
||||
### Local Development
|
||||
|
||||
1. Make changes to files in `chrome/` or `firefox/` directories
|
||||
2. Reload the extension:
|
||||
- **Chrome**: Go to `chrome://extensions/` and click reload icon
|
||||
- **Firefox**: Go to `about:debugging` and click reload
|
||||
3. Test your changes
|
||||
|
||||
### Debugging
|
||||
|
||||
- **Background Script**: Check browser console in extension management page
|
||||
- **Content Script**: Check page console (F12)
|
||||
- **Popup**: Right-click popup and select "Inspect"
|
||||
|
||||
## Privacy
|
||||
|
||||
- No data is sent to external servers
|
||||
- All rules are stored locally in browser storage
|
||||
- No analytics or tracking
|
||||
- No network requests made by the extension
|
||||
|
||||
## License
|
||||
|
||||
This extension is provided as-is for personal and educational use.
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or feature requests, please contact Andy Dixon.
|
||||
|
||||
## Version History
|
||||
|
||||
### 1.0.0 (Initial Release)
|
||||
- URL pattern matching
|
||||
- Element selector matching
|
||||
- Combined URL + Element matching
|
||||
- JavaScript execution
|
||||
- CSS injection
|
||||
- Bootstrap dark theme UI
|
||||
- Add/Edit/Delete rules
|
||||
- Enable/Disable toggle
|
||||
- Persistent storage
|
||||
- Chrome and Firefox support
|
||||
Reference in New Issue
Block a user