Skip to main content

Getting Started Guide (Deprecated)

This page is outdated. Please refer to the current documentation:

Quick setup guide for using the Empirical Ignition Perspective Component Schema validation tools.

📋 Prerequisites​

Before you begin, ensure you have:

  • Python 3.10 or newer installed
  • UV package manager (recommended) or pip
  • Access to Ignition Perspective project files
  • Basic familiarity with Ignition development

🛠ī¸ Installation​

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup the project
git clone <repository-url>
cd empirical-ignition-perspective-component-schema

# Install dependencies
uv sync

Option 2: Using pip​

# Clone the project
git clone <repository-url>
cd empirical-ignition-perspective-component-schema

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

đŸŽ¯ Basic Usage​

1. Lint Any Directory​

Point the linter at any directory and it recursively finds view.json and .py files:

# Lint everything under a folder
ignition-lint --target /path/to/any/folder

# With detailed output
ignition-lint -t /path/to/any/folder --verbose

# JSON output for programmatic use
ignition-lint -t /path/to/any/folder --report-format json

2. Lint a Full Ignition Project​

If your directory follows the standard Ignition layout:

# All checks (Perspective, naming, scripts)
ignition-lint --project /path/to/ignition/project --profile full

3. Lint a Subdirectory​

Focus on just one part of the project:

# Only Perspective views in a specific folder
ignition-lint -t /path/to/views/MyScreen --checks perspective

# Only scripts
ignition-lint -t /path/to/scripts --checks scripts

📊 Understanding Results​

Severity Levels​

  • ❌ ERROR: Critical issues that will cause runtime failures
  • ⚠ī¸ WARNING: Compatibility or best practice issues
  • ℹī¸ INFO: Informational insights and suggestions
  • 💄 STYLE: Code style and documentation improvements

Common Issues and Fixes​

Component Schema Violations​

# Example error
❌ SCHEMA_VALIDATION: 'style-list' is not one of ['scalar', 'color', 'object']

# Fix: Update the binding transform outputType
"outputType": "scalar"  // Instead of "style-list"

Jython Script Issues​

# Example error
❌ JYTHON_IGNITION_INDENTATION_REQUIRED: Lines [1, 2] have no indentation

# Fix: Ensure ALL lines in Ignition inline scripts are indented
if value == -1:     # ❌ No indentation
    return False

    if value == -1:     # ✅ Properly indented
        return False

Python Syntax Issues​

# Example error
❌ SYNTAX_ERROR: Missing parentheses in call to 'print'

# Fix: Use function syntax instead of statement
print 'hello'       # ❌ Python 2 style
print('hello')      # ✅ Python 3 compatible

🔧 Configuration​

Project-Specific Configuration​

Create a .ignition-lint.json file in your project root:

{
  "perspective": {
    "views_directory": "com.inductiveautomation.perspective/views",
    "strict_mode": true,
    "ignore_patterns": ["**/temp/**", "**/backup/**"]
  },
  "scripts": {
    "script_directory": "ignition/script-python",
    "python_version": "2.7",
    "check_imports": true
  },
  "output": {
    "format": "json",
    "include_suggestions": true,
    "verbose": false
  }
}

IDE Integration​

VSCode Setup​

  1. Install the Python extension
  2. Add to your settings.json:
{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "files.associations": {
    "*.json": "jsonc"
  },
  "json.schemas": [
    {
      "fileMatch": ["**/perspective/views/**/view.json"],
      "url": "./schemas/core-ia-components-schema-robust.json"
    }
  ]
}

Pre-commit Hooks​

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: ignition-perspective-lint
        name: Ignition Perspective Linter
        entry: uv run python tools/ignition-perspective-linter.py
        language: system
        files: \.json$
        args: [--target, .]
        pass_filenames: false

đŸŽ¯ Common Workflows​

Development Workflow​

# 1. Edit your Perspective views or scripts
# 2. Validate changes
uv run python tools/ignition-perspective-linter.py --target path/to/modified/views

# 3. Fix any issues found
# 4. Re-validate to confirm fixes
# 5. Commit your changes

CI/CD Integration​

# Add to your CI pipeline
name: Validate Ignition Project
run: |
  uv run python tools/ignition-perspective-linter.py --target ./perspective/views
  uv run python tools/ignition-script-linter.py --target ./script-python
  
  # Fail the build if critical errors are found
  if [ $? -ne 0 ]; then
    echo "Critical validation errors found!"
    exit 1
  fi

Code Review Process​

# Before creating a pull request
uv run python tools/ignition-perspective-linter.py --target . --output pr-validation.json

# Share the validation results with your team
# Address any ERROR or WARNING level issues
# Document any intentional deviations

🐛 Troubleshooting​

Common Installation Issues​

UV not found:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your terminal

Permission errors:

# Use user installation
pip install --user -r requirements.txt

Module not found errors:

# Ensure you're in the right directory and environment
cd empirical-ignition-perspective-component-schema
uv sync  # or pip install -r requirements.txt

Common Validation Issues​

Too many style issues:

# Suppress noisy rules during initial adoption
ignition-lint -p ./my-project --profile full --ignore-codes NAMING_PARAMETER,MISSING_DOCSTRING,LONG_LINE

# Or create a .ignition-lintignore file for path-based suppression
# See docs/SUPPRESSION.md for the full guide

False positives on valid code:

  • Suppress individual lines with # ignition-lint: disable=CODE (Python scripts only)
  • Use .ignition-lintignore to exclude generated or template directories
  • Check if your Ignition version is supported
  • Report persistent false positives as GitHub issues

Performance with large projects:

# Process directories in smaller batches
uv run python tools/ignition-perspective-linter.py --target ./views/specific-folder

📚 Next Steps​

  1. Read the Documentation: Explore docs/ for detailed guides
  2. Review Examples: Check examples/ for real-world usage patterns
  3. Integrate with Your Workflow: Set up pre-commit hooks and CI/CD
  4. Customize for Your Project: Configure validation rules for your needs
  5. Contribute Back: Share improvements and report issues

🤝 Getting Help​

  • Documentation: Check the docs/ directory
  • Examples: Review the examples/ directory
  • Issues: Open a GitHub issue for bugs or questions
  • Community: Join the discussion in project issues

Next: Read LINTER_USAGE.md for detailed tool documentation