# Hooks System

## Overview

The Hooks system is an event-driven architecture that allows other resources to register callback functions for specific events within the nolag\_properties resource. This system enables seamless integration with other resources and provides extensibility for custom functionality.

## API Reference

### Registering Hooks

```lua
local hookId = exports.nolag_properties:registerHook(event, callback)
```

**Parameters:**

* `event` (string): The name of the event to listen for
* `callback` (function): Function to execute when the event is triggered

**Returns:**

* `hookId` (integer): Unique identifier for the registered hook

**Example:**

```lua
-- Register a hook for property purchases
local hookId = exports.nolag_properties:registerHook('buyProperty', function(data)
    print(('Player %s bought property %s'):format(data.source, data.propertyId))
    
    -- Return false to cancel the purchase
    if someCondition then
        return false
    end
    
    -- Return true or nothing to allow the event to continue
    return true
end)
```

### Removing Hooks

```lua
exports.nolag_properties:removeHooks(hookId)
```

**Parameters:**

* `hookId` (integer): The ID returned from `registerHook`

**Example:**

```lua
exports.nolag_properties:removeHooks(hookId)
```

## Event Cancellation

Hooks can prevent events from continuing by returning `false`. This is useful for:

* Adding custom validation logic
* Implementing permission systems
* Preventing actions based on custom conditions

```lua
exports.nolag_properties:registerHook('buyProperty', function(data)
    -- Custom validation
    if not hasPermissionToBuy(data.source) then
        TriggerClientEvent('chat:addMessage', data.source, {
            args = {'System', 'You do not have permission to buy properties'}
        })
        return false -- Cancels the purchase
    end
    
    -- Allow the purchase to continue
    return true
end)
```

## Best Practices

### 1. Keep Hooks Fast

Hooks should execute quickly to avoid performance issues. Avoid:

* Database queries in hooks (use async patterns)
* Heavy computations
* Long-running operations

### 2. Error Handling

Always implement proper error handling in your hooks:

```lua
exports.nolag_properties:registerHook('buyProperty', function(data)
    local success, result = pcall(function()
        -- Your hook logic here
        return myCustomLogic(data)
    end)
    
    if not success then
        print('Hook error:', result)
        return true -- Don't cancel the event due to errors
    end
    
    return result
end)
```

### 3. Resource Cleanup

Hooks are automatically cleaned up when resources stop, but you can manually remove them:

```lua
-- Store hook IDs for manual cleanup
local hookIds = {}

-- Register hooks
hookIds.buyProperty = exports.nolag_properties:registerHook('buyProperty', buyPropertyHandler)
hookIds.rentProperty = exports.nolag_properties:registerHook('rentProperty', rentPropertyHandler)

-- Manual cleanup when needed
AddEventHandler('onResourceStop', function(resourceName)
    if resourceName == GetCurrentResourceName() then
        for _, hookId in pairs(hookIds) do
            exports.nolag_properties:removeHooks(hookId)
        end
    end
end)
```

## Usage Examples

### Example 1: Logging System

```lua
-- Log all property transactions
exports.nolag_properties:registerHook('buyProperty', function(data)
    local message = ('Property %s purchased by player %s'):format(data.propertyId, data.source)
    -- Send to your logging system
    TriggerEvent('mylogging:log', 'property', message)
    return true
end)

exports.nolag_properties:registerHook('rentProperty', function(data)
    local message = ('Property %s rented by player %s for %s days'):format(
        data.propertyId, 
        data.source, 
        data.rentDays
    )
    TriggerEvent('mylogging:log', 'property', message)
    return true
end)
```

### Example 2: Permission System

```lua
-- Custom permission system
local function hasPropertyPermission(source, action)
    -- Your permission logic here
    return exports['mypermissions']:hasPermission(source, 'property.' .. action)
end

exports.nolag_properties:registerHook('buyProperty', function(data)
    if not hasPropertyPermission(data.source, 'buy') then
        TriggerClientEvent('mynotifications:notify', data.source, 'No permission to buy properties', 'error')
        return false
    end
    return true
end)
```

### Example 3: Economy Integration

```lua
-- Custom economy integration
exports.nolag_properties:registerHook('buyProperty', function(data)
    -- Add bonus for VIP players
    if exports['myvip']:isVIP(data.source) then
        exports['myeconomy']:addMoney(data.source, 'bank', 10000, 'VIP property purchase bonus')
    end
    
    -- Update statistics
    exports['mystats']:incrementStat(data.source, 'properties_bought', 1)
    
    return true
end)
```

## Troubleshooting

### Common Issues

1. **Hook not triggering**
   * Verify the event name is spelled correctly
   * Check that the resource is started after nolag\_properties
   * Ensure ox\_lib dependency is met
2. **Performance warnings**
   * Review hook logic for expensive operations
   * Move heavy operations to async handlers
   * Consider caching frequently accessed data
3. **Events getting cancelled unexpectedly**
   * Check all registered hooks for the event
   * Verify return values (undefined/nil is treated as true)
   * Add logging to identify which hook is cancelling

### Debug Tips

```lua
-- Add logging to your hooks for debugging
exports.nolag_properties:registerHook('buyProperty', function(data)
    print('buyProperty hook triggered:', json.encode(data))
    
    local result = myCustomLogic(data)
    print('buyProperty hook result:', result)
    
    return result
end)
```