# element-controller

**Repository Path**: codeleep/element-controller

## Basic Information

- **Project Name**: element-controller
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-16
- **Last Updated**: 2025-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Element Controller Chrome Extension

A powerful Chrome extension that allows you to control element visibility on websites using URL pattern matching and CSS selectors.

## Features

- 🎯 **URL Pattern Matching**: Configure rules for specific websites using wildcard patterns
- 🎛️ **Element Control**: Hide or show elements using CSS selectors
- 📱 **Real-time Updates**: Automatically applies rules when page content changes (SPA support)
- 💾 **Persistent Configuration**: All settings are saved and synced across Chrome instances
- 🔍 **Live Testing**: Test selectors and highlight elements in real-time
- 📊 **Visual Feedback**: Clear status indicators and match counts

## Installation

### Development Installation

1. **Download/Clone the Extension**
   ```bash
   git clone <repository-url>
   cd element-controller
   ```

2. **Generate Icons** (Optional)
   - Open `create_icons.html` in your browser
   - Right-click each icon and save as PNG files in the `icons/` folder
   - Or replace the icon placeholder files with your own 16x16, 48x48, and 128x128 PNG icons

3. **Load in Chrome**
   - Open Chrome and go to `chrome://extensions/`
   - Enable "Developer mode" (toggle in top-right corner)
   - Click "Load unpacked"
   - Select the `element-controller` folder
   - The extension should now appear in your extensions list

## Usage

### 1. Creating URL Rules

1. Click the Element Controller icon in the Chrome toolbar
2. Go to the "URL Rules" tab
3. Click "Add URL Rule"
4. Enter a URL pattern using wildcards:
   - `*.example.com/*` - Matches any subdomain of example.com
   - `https://specific-site.com/page/*` - Matches specific pages
   - `*://social-media.com/*` - Matches any protocol

### 2. Creating Element Rules

1. Select a URL rule from the dropdown in the "Element Rules" tab
2. Click "Add Element Rule"
3. Enter a CSS selector:
   - `.advertisement` - Hide elements with class "advertisement"
   - `#sidebar` - Target element with ID "sidebar"
   - `div[data-role="banner"]` - Complex attribute selectors
4. Choose "Hide" or "Show" action
5. Use "Test Selector" to verify it finds the right elements
6. Use "Highlight Elements" to visually see what will be affected

### 3. Testing and Validation

- The extension provides real-time feedback on:
  - How many elements match your selector
  - Whether your URL pattern matches the current page
  - Visual highlighting of selected elements

## File Structure

```
element-controller/
├── manifest.json              # Extension configuration
├── popup/
│   ├── popup.html            # Main interface
│   ├── popup.css             # Styling
│   └── popup.js              # UI logic
├── content/
│   └── content.js            # Page content manipulation
├── background/
│   └── background.js         # Background service worker
├── utils/
│   ├── storage.js            # Data persistence
│   ├── urlMatcher.js         # URL pattern matching
│   └── elementController.js  # Element manipulation
├── icons/
│   ├── icon16.png           # Extension icons
│   ├── icon48.png
│   └── icon128.png
└── README.md                # This file
```

## Technical Details

### Architecture

- **Manifest V3**: Uses the latest Chrome extension format
- **Modular Design**: Separated concerns for maintainability
- **Event-Driven**: Responds to DOM changes and URL navigation
- **Performance Optimized**: Debounced DOM monitoring and efficient selectors

### Key Features Implementation

#### URL Matching
- Converts wildcard patterns to regular expressions
- Supports complex matching scenarios
- Provides pattern suggestions based on current page

#### Element Control
- Uses CSS classes for reliable show/hide functionality
- Preserves original element styles
- Handles dynamic content with MutationObserver

#### SPA Support
- Monitors URL changes through multiple methods
- Reapplies rules when page content changes
- Handles programmatic navigation

### Storage Format

```javascript
{
  "urlRules": [
    {
      "id": "unique_id",
      "pattern": "*.example.com/*",
      "enabled": true,
      "elementRules": [
        {
          "id": "element_id",
          "selector": ".advertisement",
          "action": "hide",
          "enabled": true
        }
      ]
    }
  ]
}
```

## Troubleshooting

### Common Issues

1. **Rules not applying**
   - Check if URL pattern matches current page
   - Verify element selector is correct
   - Ensure both URL rule and element rule are enabled

2. **Selector not finding elements**
   - Use browser DevTools to inspect elements
   - Test selector in console: `document.querySelectorAll('your-selector')`
   - Try simpler selectors first

3. **SPA navigation issues**
   - The extension automatically handles most SPA frameworks
   - If issues persist, try refreshing the page after navigation

### Debugging

- Open browser console and look for "Element Controller" log messages
- Use the test functions in the popup to verify functionality
- Check Chrome extension developer tools for detailed error messages

### Debug Functions

In the browser console, you can use:
```javascript
// Get content script debug info
getElementControllerDebugInfo()

// Check background script status
getElementControllerBackgroundInfo()
```

## Security and Privacy

- All data is stored locally in Chrome's sync storage
- No data is sent to external servers
- Only accesses web pages when rules are configured
- Follows Chrome extension security best practices

## Browser Compatibility

- Chrome 88+ (Manifest V3 requirement)
- Chromium-based browsers (Edge, Brave, etc.)

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly across different websites
5. Submit a pull request

## License

This project is licensed under the MIT License.

## Support

For issues and feature requests, please create an issue in the repository.

---

**Note**: Remember to replace placeholder icons with proper icon files before publishing to the Chrome Web Store.