Skip to content

Commit 77502f2

Browse files
jorikfonjorikfon
committed
Update documentation
1 parent 1f68d1a commit 77502f2

File tree

1 file changed

+172
-0
lines changed

1 file changed

+172
-0
lines changed

‎README.md

+172
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Phone Book Module for MIKOPBX
2+
3+
A comprehensive phone book management module for MIKOPBX that provides caller ID management, contact storage, and integration with the PBX system's inbound and outbound calls.
4+
5+
## Features
6+
7+
- Real-time caller ID lookup for inbound and outbound calls
8+
- Contact management with formatted number display
9+
- Excel file import support
10+
- Full-text search capabilities
11+
- Input mask toggling for phone number formatting
12+
- Asterisk AGI integration for call processing
13+
- DataTable-based web interface
14+
15+
## System Requirements
16+
17+
- MIKOPBX version 2024.1.114 or higher
18+
- Modern web browser with JavaScript enabled
19+
20+
## Database Structure
21+
22+
The module uses SQLite database located at:
23+
`/storage/usbdisk1/mikopbx/custom_modules/ModulePhoneBook/db/module.db`
24+
25+
### Phone Book Table (m_PhoneBook)
26+
27+
Main table storing contact information:
28+
29+
```sql
30+
CREATE TABLE m_PhoneBook (
31+
id INTEGER PRIMARY KEY AUTO_INCREMENT,
32+
number INTEGER, -- Normalized number (1 + last 9 digits)
33+
number_rep VARCHAR(255), -- Display format (e.g., +7(906)555-43-43)
34+
call_id VARCHAR(255), -- Caller ID display name
35+
search_index TEXT -- Combined search field for full-text search
36+
);
37+
38+
-- Indexes
39+
CREATE INDEX number ON m_PhoneBook (number);
40+
CREATE INDEX CallerID ON m_PhoneBook (call_id);
41+
```
42+
43+
### Settings Table (m_ModulePhoneBook)
44+
45+
Module configuration storage:
46+
47+
```sql
48+
CREATE TABLE m_ModulePhoneBook (
49+
id INTEGER PRIMARY KEY AUTO_INCREMENT,
50+
disableInputMask INTEGER DEFAULT 0 -- Toggle for input mask functionality
51+
);
52+
```
53+
54+
## Phone Number Format
55+
56+
The module uses a specific format for storing phone numbers:
57+
1. Original number gets cleaned from any non-digit characters
58+
2. Only the last 9 digits are kept
59+
3. Digit "1" is added at the beginning
60+
4. The result is stored in the 'number' field
61+
62+
Example:
63+
```
64+
Original: +7 (906) 555-43-43
65+
Cleaned: 79065554343
66+
Last 9: 065554343
67+
Stored: 1065554343
68+
```
69+
70+
This format ensures:
71+
- Consistent number storage
72+
- Quick lookups
73+
- Independence from country codes
74+
- Compatibility with various number formats
75+
76+
## Core Components
77+
78+
### Business Logic (Lib/)
79+
80+
1. **PhoneBookConf.php** - Core configuration and PBX integration:
81+
- Manages Asterisk dialplan integration
82+
- Processes incoming/outgoing call routing
83+
84+
2. **PhoneBookAgi.php** - Asterisk AGI integration:
85+
- Real-time caller ID lookup
86+
- Handles both incoming and outgoing calls
87+
- Sets caller ID display names
88+
89+
3. **PhoneBookImport.php** - Data import functionality:
90+
- Excel file processing
91+
- Data validation and normalization
92+
- Bulk contact import
93+
94+
### Frontend Features
95+
96+
The module includes several JavaScript components:
97+
98+
1. **DataTable Integration:**
99+
- Server-side processing
100+
- Real-time search
101+
- Automatic page length calculation
102+
- Saved state persistence
103+
104+
2. **Input Masking:**
105+
- Dynamic phone number formatting
106+
- Multiple format support
107+
- Configurable masks
108+
- Toggle functionality
109+
110+
3. **Excel Import:**
111+
- File upload with progress tracking
112+
- Background processing
113+
- Error handling
114+
- Automatic data normalization
115+
116+
## Usage
117+
118+
### Managing Contacts
119+
120+
```php
121+
// Example: Adding a new contact
122+
$contact = new PhoneBook();
123+
$contact->number = '1065554343'; // Normalized format
124+
$contact->number_rep = '+7(906)555-43-43'; // Display format
125+
$contact->call_id = 'John Doe';
126+
$contact->search_index = 'johndoe1065554343+7(906)555-43-43';
127+
$contact->save();
128+
```
129+
130+
### Excel Import Format
131+
132+
The module accepts Excel files with the following structure:
133+
```
134+
| Name/Company | Phone Number |
135+
|-----------------|-------------------|
136+
| John Doe | +1 (555) 123-4567 |
137+
| ACME Corp | +1-777-888-9999 |
138+
```
139+
140+
Phone numbers are automatically normalized during import.
141+
142+
## Development
143+
144+
### Class Structure
145+
146+
```
147+
ModulePhoneBook/
148+
├── Lib/
149+
│ ├── PhoneBookConf.php # PBX integration
150+
│ ├── PhoneBookAgi.php # Asterisk AGI handler
151+
│ └── PhoneBookImport.php # Import processor
152+
├── Models/
153+
│ ├── PhoneBook.php # Contact storage
154+
│ └── Settings.php # Configuration
155+
├── public/
156+
└── assets/
157+
└── js/
158+
└── src/
159+
├── module-phonebook-datatable.js
160+
├── module-phonebook-import.js
161+
└── module-phonebook-index.js
162+
```
163+
164+
## License
165+
166+
GNU General Public License v3.0 - see LICENSE file for details.
167+
168+
## Support
169+
170+
- Documentation: [https://docs.mikopbx.com/mikopbx/modules/miko/phone-book](https://docs.mikopbx.com/mikopbx/modules/miko/phone-book)
171+
- Email: [email protected]
172+
- Issues: GitHub issue tracker

0 commit comments

Comments
 (0)