@maccesar/titools 2.2.3 → 2.2.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -27
- package/lib/commands/update.js +80 -101
- package/package.json +1 -1
- package/skills/alloy-guides/SKILL.md +31 -31
- package/skills/alloy-guides/references/CONCEPTS.md +3 -3
- package/skills/alloy-guides/references/CONTROLLERS.md +1 -1
- package/skills/alloy-guides/references/MODELS.md +6 -6
- package/skills/alloy-guides/references/VIEWS_WITHOUT_CONTROLLERS.md +1 -1
- package/skills/alloy-guides/references/VIEWS_XML.md +1 -1
- package/skills/alloy-guides/references/WIDGETS.md +1 -1
- package/skills/alloy-howtos/SKILL.md +27 -27
- package/skills/alloy-howtos/references/best_practices.md +9 -9
- package/skills/alloy-howtos/references/cli_reference.md +14 -14
- package/skills/alloy-howtos/references/config_files.md +16 -16
- package/skills/alloy-howtos/references/custom_tags.md +16 -16
- package/skills/alloy-howtos/references/debugging_troubleshooting.md +11 -15
- package/skills/alloy-howtos/references/samples.md +19 -19
- package/skills/purgetss/SKILL.md +11 -1
- package/skills/purgetss/references/animation-system.md +1 -1
- package/skills/purgetss/references/cli-commands.md +3 -3
- package/skills/purgetss/references/customization-deep-dive.md +1 -1
- package/skills/purgetss/references/dynamic-component-creation.md +1 -1
- package/skills/purgetss/references/icon-fonts.md +4 -0
- package/skills/purgetss/references/installation-setup.md +8 -1
- package/skills/purgetss/references/migration-guide.md +4 -0
- package/skills/purgetss/references/tikit-components.md +193 -204
- package/skills/purgetss/references/ui-ux-design.md +1 -1
- package/skills/ti-expert/SKILL.md +78 -118
- package/skills/ti-expert/references/alloy-builtins.md +18 -18
- package/skills/ti-expert/references/alloy-structure.md +21 -21
- package/skills/ti-expert/references/anti-patterns.md +15 -15
- package/skills/ti-expert/references/cli-expert.md +15 -15
- package/skills/ti-expert/references/code-conventions.md +38 -38
- package/skills/ti-expert/references/contracts.md +8 -8
- package/skills/ti-expert/references/controller-patterns.md +14 -14
- package/skills/ti-expert/references/error-handling.md +11 -11
- package/skills/ti-expert/references/examples.md +12 -12
- package/skills/ti-expert/references/migration-patterns.md +24 -24
- package/skills/ti-expert/references/patterns.md +10 -10
- package/skills/ti-expert/references/performance-listview.md +16 -16
- package/skills/ti-expert/references/performance-optimization.md +41 -41
- package/skills/ti-expert/references/security-device.md +22 -22
- package/skills/ti-expert/references/security-fundamentals.md +19 -19
- package/skills/ti-expert/references/state-management.md +33 -33
- package/skills/ti-expert/references/testing-e2e-ci.md +25 -25
- package/skills/ti-expert/references/testing-unit.md +24 -24
- package/skills/ti-expert/references/theming.md +15 -15
- package/skills/ti-guides/SKILL.md +58 -60
- package/skills/ti-guides/references/advanced-data-and-images.md +33 -33
- package/skills/ti-guides/references/android-manifest.md +15 -15
- package/skills/ti-guides/references/app-distribution.md +70 -166
- package/skills/ti-guides/references/application-frameworks.md +96 -114
- package/skills/ti-guides/references/cli-reference.md +294 -294
- package/skills/ti-guides/references/coding-best-practices.md +42 -33
- package/skills/ti-guides/references/commonjs-advanced.md +57 -51
- package/skills/ti-guides/references/hello-world.md +36 -36
- package/skills/ti-guides/references/hyperloop-native-access.md +66 -66
- package/skills/ti-guides/references/javascript-primer.md +83 -101
- package/skills/ti-guides/references/reserved-words.md +9 -9
- package/skills/ti-guides/references/resources.md +75 -83
- package/skills/ti-guides/references/style-and-conventions.md +35 -28
- package/skills/ti-guides/references/tiapp-config.md +110 -74
- package/skills/ti-howtos/SKILL.md +88 -92
- package/skills/ti-howtos/references/android-platform-deep-dives.md +104 -104
- package/skills/ti-howtos/references/automation-fastlane-appium.md +39 -39
- package/skills/ti-howtos/references/buffer-codec-streams.md +60 -60
- package/skills/ti-howtos/references/cross-platform-development.md +115 -136
- package/skills/ti-howtos/references/debugging-profiling.md +167 -181
- package/skills/ti-howtos/references/extending-titanium.md +121 -121
- package/skills/ti-howtos/references/google-maps-v2.md +84 -82
- package/skills/ti-howtos/references/ios-map-kit.md +65 -60
- package/skills/ti-howtos/references/ios-platform-deep-dives.md +123 -123
- package/skills/ti-howtos/references/local-data-sources.md +79 -78
- package/skills/ti-howtos/references/location-and-maps.md +116 -120
- package/skills/ti-howtos/references/media-apis.md +87 -86
- package/skills/ti-howtos/references/notification-services.md +250 -260
- package/skills/ti-howtos/references/remote-data-sources.md +98 -93
- package/skills/ti-howtos/references/tutorials.md +226 -216
- package/skills/ti-howtos/references/using-modules.md +73 -102
- package/skills/ti-howtos/references/web-content-integration.md +101 -103
- package/skills/ti-howtos/references/webpack-build-pipeline.md +52 -44
- package/skills/ti-ui/SKILL.md +85 -85
- package/skills/ti-ui/references/accessibility-deep-dive.md +57 -57
- package/skills/ti-ui/references/animation-and-matrices.md +79 -79
- package/skills/ti-ui/references/application-structures.md +96 -99
- package/skills/ti-ui/references/custom-fonts-styling.md +99 -99
- package/skills/ti-ui/references/event-handling.md +58 -58
- package/skills/ti-ui/references/gestures.md +62 -64
- package/skills/ti-ui/references/icons-and-splash-screens.md +88 -88
- package/skills/ti-ui/references/layouts-and-positioning.md +87 -97
- package/skills/ti-ui/references/listviews-and-performance.md +107 -107
- package/skills/ti-ui/references/orientation.md +87 -88
- package/skills/ti-ui/references/platform-ui-android.md +87 -81
- package/skills/ti-ui/references/platform-ui-ios.md +63 -61
- package/skills/ti-ui/references/scrolling-views.md +29 -29
- package/skills/ti-ui/references/tableviews.md +56 -56
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# UI/UX Design Patterns for Titanium SDK with PurgeTSS
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A guide to building accessible and performant mobile UIs using Titanium SDK and PurgeTSS utility classes.
|
|
4
4
|
|
|
5
5
|
## 1. Common UI Components
|
|
6
6
|
|
|
@@ -5,46 +5,44 @@ argument-hint: "[architecture-topic]"
|
|
|
5
5
|
allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# Titanium
|
|
8
|
+
# Titanium expert
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Practical architecture and implementation guidance for Titanium SDK apps (Alloy and Classic). Focus on maintainability, clear boundaries, and low-friction testing.
|
|
11
11
|
|
|
12
|
-
## Project
|
|
12
|
+
## Project detection
|
|
13
13
|
|
|
14
|
-
:::info
|
|
15
|
-
This skill
|
|
14
|
+
:::info Auto-detects Alloy vs Classic projects
|
|
15
|
+
This skill detects project type automatically and tailors guidance.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
**Alloy project indicators:**
|
|
17
|
+
Alloy indicators:
|
|
20
18
|
- `app/` folder (MVC structure)
|
|
21
19
|
- `app/views/`, `app/controllers/` folders
|
|
22
20
|
- `alloy.jmk` or `config.json` files
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
Classic indicators:
|
|
25
23
|
- `Resources/` folder with `app.js` at root
|
|
26
24
|
- No `app/` folder structure
|
|
27
25
|
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
26
|
+
Behavior:
|
|
27
|
+
- Alloy detected: provides Alloy MVC patterns and Backbone.js guidance
|
|
28
|
+
- Classic detected: avoids Alloy-only patterns and recommends Classic options or migration
|
|
29
|
+
- Unknown: asks the user to clarify the project type
|
|
32
30
|
:::
|
|
33
31
|
|
|
34
32
|
## Workflow
|
|
35
33
|
|
|
36
|
-
1.
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
40
|
-
5.
|
|
41
|
-
6.
|
|
34
|
+
1. Architecture: define structure (`lib/api`, `lib/services`, `lib/helpers`)
|
|
35
|
+
2. Data strategy: choose Models (SQLite) or Collections (API)
|
|
36
|
+
3. Contracts: define I/O specs between layers
|
|
37
|
+
4. Implementation: write XML views and ES6+ controllers
|
|
38
|
+
5. Quality: testing, error handling, logging, performance
|
|
39
|
+
6. Cleanup: implement a `cleanup()` pattern for memory management
|
|
42
40
|
|
|
43
|
-
## Quick
|
|
41
|
+
## Quick start example
|
|
44
42
|
|
|
45
|
-
Minimal example
|
|
43
|
+
Minimal example that matches the conventions:
|
|
46
44
|
|
|
47
|
-
|
|
45
|
+
View (`views/user/card.xml`)
|
|
48
46
|
```xml
|
|
49
47
|
<Alloy>
|
|
50
48
|
<View id="cardContainer">
|
|
@@ -60,7 +58,7 @@ Minimal example following all conventions:
|
|
|
60
58
|
</Alloy>
|
|
61
59
|
```
|
|
62
60
|
|
|
63
|
-
|
|
61
|
+
Styles (`styles/user/card.tss`)
|
|
64
62
|
```tss
|
|
65
63
|
"#cardContainer": { left: 8, right: 8, top: 8, height: Ti.UI.SIZE, borderRadius: 12, backgroundColor: '#fff' }
|
|
66
64
|
"#headerRow": { layout: 'horizontal', left: 12, right: 12, top: 12, height: Ti.UI.SIZE, width: Ti.UI.FILL }
|
|
@@ -69,7 +67,7 @@ Minimal example following all conventions:
|
|
|
69
67
|
"#viewProfileBtn": { left: 12, right: 12, bottom: 12, height: 40, width: Ti.UI.FILL, borderRadius: 6, backgroundColor: '#2563eb', color: '#fff' }
|
|
70
68
|
```
|
|
71
69
|
|
|
72
|
-
|
|
70
|
+
Controller (`controllers/user/card.js`)
|
|
73
71
|
```javascript
|
|
74
72
|
const { Navigation } = require('services/navigation')
|
|
75
73
|
|
|
@@ -89,7 +87,7 @@ function cleanup() {
|
|
|
89
87
|
$.cleanup = cleanup
|
|
90
88
|
```
|
|
91
89
|
|
|
92
|
-
|
|
90
|
+
Service (`lib/services/navigation.js`)
|
|
93
91
|
```javascript
|
|
94
92
|
exports.Navigation = {
|
|
95
93
|
open(route, params = {}) {
|
|
@@ -106,133 +104,95 @@ exports.Navigation = {
|
|
|
106
104
|
}
|
|
107
105
|
```
|
|
108
106
|
|
|
109
|
-
## Code
|
|
107
|
+
## Code standards (low freedom)
|
|
110
108
|
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
-
|
|
114
|
-
-
|
|
115
|
-
-
|
|
116
|
-
-
|
|
109
|
+
- No semicolons: let ASI handle it
|
|
110
|
+
- Modern syntax: `const/let`, destructuring, template literals
|
|
111
|
+
- `applyProperties()`: batch UI updates to reduce bridge crossings
|
|
112
|
+
- Memory cleanup: any controller with global listeners must set `$.cleanup = cleanup`
|
|
113
|
+
- Error handling: use AppError classes, log with context, never swallow errors
|
|
114
|
+
- Testable code: inject dependencies, avoid hard coupling
|
|
117
115
|
|
|
118
|
-
## Titanium
|
|
116
|
+
## Titanium style sheets rules (low freedom)
|
|
119
117
|
|
|
120
|
-
:::danger
|
|
121
|
-
Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties
|
|
118
|
+
:::danger Critical: platform-specific properties require modifiers
|
|
119
|
+
Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties without platform modifiers breaks cross-platform builds.
|
|
122
120
|
|
|
123
|
-
|
|
121
|
+
Example of the damage:
|
|
124
122
|
```tss
|
|
125
|
-
//
|
|
123
|
+
// Wrong: adds Ti.UI.iOS to Android project
|
|
126
124
|
"#mainWindow": {
|
|
127
|
-
statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
|
|
125
|
+
statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
|
|
128
126
|
}
|
|
129
127
|
```
|
|
130
128
|
|
|
131
|
-
|
|
129
|
+
Correct: always use platform modifiers
|
|
132
130
|
```tss
|
|
133
|
-
//
|
|
131
|
+
// Correct: only adds to iOS
|
|
134
132
|
"#mainWindow[platform=ios]": {
|
|
135
133
|
statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
|
|
136
134
|
}
|
|
137
135
|
```
|
|
138
136
|
|
|
139
|
-
|
|
137
|
+
Properties that always need platform modifiers:
|
|
140
138
|
- iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
|
|
141
139
|
- Android: `actionBar` configuration, any `Ti.UI.Android.*` constant
|
|
142
140
|
|
|
143
|
-
|
|
141
|
+
Available modifiers: `[platform=ios]`, `[platform=android]`, `[formFactor=handheld]`, `[formFactor=tablet]`, `[if=Alloy.Globals.customVar]`
|
|
144
142
|
|
|
145
|
-
|
|
143
|
+
For more platform-specific patterns, see the `ti-ui` skill.
|
|
146
144
|
:::
|
|
147
145
|
|
|
148
|
-
|
|
149
|
-
- Three layout modes: `layout: 'horizontal'`, `layout: 'vertical'`, and composite (default
|
|
150
|
-
- No padding on container Views
|
|
146
|
+
Titanium layout system:
|
|
147
|
+
- Three layout modes: `layout: 'horizontal'`, `layout: 'vertical'`, and composite (default, no `layout` needed)
|
|
148
|
+
- No padding on container Views: use margins on children instead
|
|
151
149
|
- `width: Ti.UI.FILL` fills available space (preferred), `width: '100%'` = 100% of parent
|
|
152
150
|
- `height: Ti.UI.SIZE` wraps content, `height: Ti.UI.FILL` fills available space
|
|
153
151
|
|
|
154
|
-
## Alloy
|
|
152
|
+
## Alloy builtins quick reference
|
|
155
153
|
|
|
156
154
|
Key builtins: `OS_IOS`/`OS_ANDROID` (compile-time), `Alloy.CFG` (config.json), `Alloy.Globals` (shared state), `$.args` (controller params), `$.destroy()` (cleanup bindings), `platform="ios"` / `formFactor="tablet"` (XML conditionals).
|
|
157
155
|
|
|
158
|
-
For the complete reference with examples, see
|
|
156
|
+
For the complete reference with examples, see [Alloy builtins and globals](references/alloy-builtins.md).
|
|
159
157
|
|
|
160
|
-
## Quick
|
|
158
|
+
## Quick decision matrix
|
|
161
159
|
|
|
162
160
|
| Question | Answer |
|
|
163
161
|
| ---------------------------------- | -------------------------------------------------------------- |
|
|
164
|
-
| How to create a new Alloy project? |
|
|
165
|
-
| Fastest way to build? |
|
|
162
|
+
| How to create a new Alloy project? | `ti create -t app --alloy` (not `--classic` + `alloy new`) |
|
|
163
|
+
| Fastest way to build? | `tn <recipe>` (using TiNy CLI wrapper) |
|
|
166
164
|
| Where does API call go? | `lib/api/` |
|
|
167
165
|
| Where does business logic go? | `lib/services/` |
|
|
168
166
|
| Where do I store auth tokens? | Keychain (iOS) / KeyStore (Android) via service |
|
|
169
167
|
| Models or Collections? | Collections for API data, Models for SQLite persistence |
|
|
170
|
-
| Ti.App.fireEvent or EventBus? |
|
|
171
|
-
| Direct navigation or service? |
|
|
172
|
-
| Inline styles or TSS files? |
|
|
168
|
+
| Ti.App.fireEvent or EventBus? | Always EventBus (Backbone.Events) |
|
|
169
|
+
| Direct navigation or service? | Always Navigation service (auto cleanup) |
|
|
170
|
+
| Inline styles or TSS files? | Always TSS files (per-controller + `app.tss` for global) |
|
|
173
171
|
| Controller 100+ lines? | Extract logic to services |
|
|
174
172
|
|
|
175
|
-
## Reference
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
180
|
-
-
|
|
181
|
-
-
|
|
182
|
-
-
|
|
183
|
-
-
|
|
184
|
-
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
-
|
|
188
|
-
-
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
-
|
|
194
|
-
-
|
|
195
|
-
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
-
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
- **[Device Security](references/security-device.md)**: Biometric auth, deep link validation, jailbreak/root detection
|
|
202
|
-
- **[State Management](references/state-management.md)**: Centralized store, reactive patterns, synchronization
|
|
203
|
-
|
|
204
|
-
### Migration
|
|
205
|
-
- **[Migration Patterns](references/migration-patterns.md)**: Step-by-step guide for modernizing legacy apps
|
|
206
|
-
|
|
207
|
-
## Specialized Titanium Skills
|
|
208
|
-
|
|
209
|
-
For specific feature implementations, defer to these specialized skills:
|
|
210
|
-
|
|
211
|
-
| Task | Use This Skill |
|
|
212
|
-
| ----------------------------------------------------- | -------------- |
|
|
213
|
-
| Location, Maps, Push Notifications, Media APIs | `ti-howtos` |
|
|
214
|
-
| UI layouts, ListViews, gestures, platform-specific UI | `ti-ui` |
|
|
215
|
-
| Alloy CLI, configuration files, debugging | `alloy-howtos` |
|
|
216
|
-
| Alloy MVC complete reference | `alloy-guides` |
|
|
217
|
-
| Hyperloop, native modules, app distribution | `ti-guides` |
|
|
218
|
-
|
|
219
|
-
## Guiding Principles
|
|
220
|
-
|
|
221
|
-
1. **Thin Controllers**: Max 100 lines. Delegate to services.
|
|
222
|
-
2. **Single Source of Truth**: One state store, not scattered Properties.
|
|
223
|
-
3. **Always Cleanup**: Every listener added = listener removed in `cleanup()`.
|
|
224
|
-
4. **Never Block UI**: All API/DB calls are async with loading states.
|
|
225
|
-
5. **Fail Gracefully**: Centralized error handling with user-friendly messages.
|
|
226
|
-
|
|
227
|
-
## Response Format
|
|
228
|
-
|
|
229
|
-
**For Architecture Questions:**
|
|
230
|
-
1. Decision: What should be done
|
|
231
|
-
2. Justification: Technical rationale
|
|
232
|
-
3. Structure: File and folder placement
|
|
233
|
-
4. Contract: Clear I/O specification
|
|
234
|
-
|
|
235
|
-
**For Implementation Tasks:**
|
|
236
|
-
1. Code First: Show implementation immediately
|
|
237
|
-
2. Minimal Comments: Explain only the "Why" for complex logic
|
|
238
|
-
3. No Explanations: Deliver exactly what was asked concisely
|
|
173
|
+
## Reference guides (progressive disclosure)
|
|
174
|
+
|
|
175
|
+
Architecture
|
|
176
|
+
- [CLI expert and TiNy](references/cli-expert.md): advanced build workflows, LiveView, TiNy (`tn`) recipes
|
|
177
|
+
- [Structure and organization](references/alloy-structure.md): models vs collections, folder maps, widget patterns, automatic cleanup
|
|
178
|
+
- [Alloy builtins and globals](references/alloy-builtins.md): `OS_IOS`/`OS_ANDROID`, `Alloy.CFG`, `Alloy.Globals`, `$.args`, compiler directives
|
|
179
|
+
- [ControllerAutoCleanup.js](assets/ControllerAutoCleanup.js): drop-in utility for automatic controller cleanup
|
|
180
|
+
- [Architectural patterns](references/patterns.md): repository, service layer, event bus, factory, singleton
|
|
181
|
+
- [Contracts and communication](references/contracts.md): layer interaction examples and JSDoc specs
|
|
182
|
+
- [Anti-patterns](references/anti-patterns.md): fat controllers, memory leaks, inline styling, direct API calls
|
|
183
|
+
|
|
184
|
+
Implementation
|
|
185
|
+
- [Code conventions](references/code-conventions.md): ES6 features, TSS design system, accessibility
|
|
186
|
+
- [Theming and dark mode](references/theming.md): theme system, Alloy.Globals palette, runtime switching, design tokens
|
|
187
|
+
- [Controller patterns](references/controller-patterns.md): templates, animation, dynamic styling
|
|
188
|
+
- [Examples](references/examples.md): API clients, SQL models, full screen examples
|
|
189
|
+
|
|
190
|
+
Quality and reliability
|
|
191
|
+
- [Unit and integration testing](references/testing-unit.md): unit testing, mocking patterns, controller testing, test helpers
|
|
192
|
+
- [E2E testing and CI/CD](references/testing-e2e-ci.md): Appium, WebdriverIO, GitHub Actions, Fastlane
|
|
193
|
+
- [Error handling and logging](references/error-handling.md): AppError classes, Logger service, validation
|
|
194
|
+
|
|
195
|
+
Performance and security
|
|
196
|
+
- [ListView and ScrollView performance](references/performance-listview.md): ListView templates, data binding, image caching, ScrollView optimization
|
|
197
|
+
- [Performance optimization](references/performance-optimization.md): bridge crossings, memory management, animations, debounce/throttle, database
|
|
198
|
+
- [Security fundamentals](references/security-fundamentals.md): token storage, certificate pinning, encryption, HTTPS, OWASP
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# Alloy
|
|
1
|
+
# Alloy builtins & globals
|
|
2
2
|
|
|
3
|
-
## Compiler
|
|
3
|
+
## Compiler directives
|
|
4
4
|
|
|
5
5
|
Alloy provides compile-time constants that are replaced with `true`/`false` during build. Use them for platform-specific code without runtime cost.
|
|
6
6
|
|
|
7
|
-
###
|
|
7
|
+
### Os_ios / os_android
|
|
8
8
|
|
|
9
9
|
```javascript
|
|
10
10
|
// These are compile-time constants — dead code is removed at build
|
|
@@ -30,7 +30,7 @@ if (OS_ANDROID) {
|
|
|
30
30
|
**Do NOT use for:** Logic that should be testable on both platforms
|
|
31
31
|
:::
|
|
32
32
|
|
|
33
|
-
###
|
|
33
|
+
### Env_dev / env_test / env_production
|
|
34
34
|
|
|
35
35
|
```javascript
|
|
36
36
|
if (ENV_DEV) {
|
|
@@ -55,7 +55,7 @@ ti build -p ios -T dist-appstore -D production
|
|
|
55
55
|
|
|
56
56
|
Shared state and utilities accessible from any controller or lib file. Set in `alloy.js`, available everywhere.
|
|
57
57
|
|
|
58
|
-
### Common
|
|
58
|
+
### Common patterns
|
|
59
59
|
|
|
60
60
|
```javascript
|
|
61
61
|
// alloy.js
|
|
@@ -83,7 +83,7 @@ Alloy.Collections.products = new Backbone.Collection()
|
|
|
83
83
|
Alloy.Collections.notifications = new Backbone.Collection()
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
-
### Access from
|
|
86
|
+
### Access from anywhere
|
|
87
87
|
|
|
88
88
|
```javascript
|
|
89
89
|
// In any controller
|
|
@@ -99,7 +99,7 @@ $.label.color = theme.primary
|
|
|
99
99
|
// <View if="Alloy.Globals.isLoggedIn">
|
|
100
100
|
```
|
|
101
101
|
|
|
102
|
-
### Globals vs
|
|
102
|
+
### Globals vs services
|
|
103
103
|
|
|
104
104
|
| Use `Alloy.Globals` for | Use a Service for |
|
|
105
105
|
| ---------------------------------- | ----------------------------- |
|
|
@@ -184,11 +184,11 @@ if (Alloy.isTablet) {
|
|
|
184
184
|
|
|
185
185
|
---
|
|
186
186
|
|
|
187
|
-
## $.args
|
|
187
|
+
## $.args , controller arguments
|
|
188
188
|
|
|
189
189
|
Every controller receives arguments via `$.args`. This is the standard way to pass data between controllers.
|
|
190
190
|
|
|
191
|
-
### Basic
|
|
191
|
+
### Basic usage
|
|
192
192
|
|
|
193
193
|
```javascript
|
|
194
194
|
// Opening controller with args
|
|
@@ -203,7 +203,7 @@ const ctrl = Alloy.createController('user/profile', {
|
|
|
203
203
|
const { userId, mode, onSave } = $.args
|
|
204
204
|
```
|
|
205
205
|
|
|
206
|
-
### Common
|
|
206
|
+
### Common patterns
|
|
207
207
|
|
|
208
208
|
```javascript
|
|
209
209
|
// Pattern 1: Default values with destructuring
|
|
@@ -242,7 +242,7 @@ function save() {
|
|
|
242
242
|
}
|
|
243
243
|
```
|
|
244
244
|
|
|
245
|
-
### $.args in
|
|
245
|
+
### $.args in widgets
|
|
246
246
|
|
|
247
247
|
Widgets also receive args, but through the `<Widget>` tag attributes:
|
|
248
248
|
|
|
@@ -269,7 +269,7 @@ For complex data, pass via `Alloy.createController()` in the parent controller i
|
|
|
269
269
|
|
|
270
270
|
## Alloy.createController / Alloy.createWidget
|
|
271
271
|
|
|
272
|
-
### Controller
|
|
272
|
+
### Controller creation
|
|
273
273
|
|
|
274
274
|
```javascript
|
|
275
275
|
// Create and open
|
|
@@ -285,7 +285,7 @@ ctrl.refresh()
|
|
|
285
285
|
ctrl.setData(newData)
|
|
286
286
|
```
|
|
287
287
|
|
|
288
|
-
### Widget
|
|
288
|
+
### Widget creation
|
|
289
289
|
|
|
290
290
|
```javascript
|
|
291
291
|
// Create widget programmatically (alternative to XML <Widget>)
|
|
@@ -321,9 +321,9 @@ users.fetch({
|
|
|
321
321
|
|
|
322
322
|
---
|
|
323
323
|
|
|
324
|
-
## Conditional
|
|
324
|
+
## Conditional code in XML
|
|
325
325
|
|
|
326
|
-
### Platform
|
|
326
|
+
### Platform conditional
|
|
327
327
|
|
|
328
328
|
```xml
|
|
329
329
|
<Alloy>
|
|
@@ -339,7 +339,7 @@ users.fetch({
|
|
|
339
339
|
</Alloy>
|
|
340
340
|
```
|
|
341
341
|
|
|
342
|
-
### Form
|
|
342
|
+
### Form factor conditional
|
|
343
343
|
|
|
344
344
|
```xml
|
|
345
345
|
<Alloy>
|
|
@@ -352,7 +352,7 @@ users.fetch({
|
|
|
352
352
|
</Alloy>
|
|
353
353
|
```
|
|
354
354
|
|
|
355
|
-
### Custom
|
|
355
|
+
### Custom conditional (if attribute)
|
|
356
356
|
|
|
357
357
|
```xml
|
|
358
358
|
<!-- Only render if condition is true at creation time -->
|
|
@@ -371,7 +371,7 @@ The `if` attribute is checked when the controller is created. It does NOT react
|
|
|
371
371
|
|
|
372
372
|
---
|
|
373
373
|
|
|
374
|
-
## Quick
|
|
374
|
+
## Quick reference
|
|
375
375
|
|
|
376
376
|
| Builtin | Type | Where Set | Mutable |
|
|
377
377
|
| ------------------- | ----------------- | ----------------- | ------- |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Alloy MVC
|
|
1
|
+
# Alloy MVC structure reference
|
|
2
2
|
|
|
3
|
-
## Standard
|
|
3
|
+
## Standard project structure
|
|
4
4
|
|
|
5
5
|
```
|
|
6
6
|
app/
|
|
@@ -35,7 +35,7 @@ app/
|
|
|
35
35
|
└── alloy.js # Collections & Global services
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
## lib/
|
|
38
|
+
## lib/ folder and module require paths
|
|
39
39
|
|
|
40
40
|
:::danger CRITICAL: lib/ Folder is FLATTENED During Build
|
|
41
41
|
When Alloy compiles, the **entire `lib/` folder is flattened to the root of Resources**. This means:
|
|
@@ -72,9 +72,9 @@ app/
|
|
|
72
72
|
```
|
|
73
73
|
:::
|
|
74
74
|
|
|
75
|
-
## Data
|
|
75
|
+
## Data layer: two approaches
|
|
76
76
|
|
|
77
|
-
### Approach
|
|
77
|
+
### Approach a: Alloy models (app/models/) - for persistence
|
|
78
78
|
|
|
79
79
|
**Use when:**
|
|
80
80
|
- You need SQLite persistence
|
|
@@ -104,7 +104,7 @@ users.fetch()
|
|
|
104
104
|
|
|
105
105
|
---
|
|
106
106
|
|
|
107
|
-
### Approach
|
|
107
|
+
### Approach b: Backbone collections direct (alloy.js) - for API data
|
|
108
108
|
|
|
109
109
|
**Use when:**
|
|
110
110
|
- Data comes from APIs
|
|
@@ -137,7 +137,7 @@ api.getFrames()
|
|
|
137
137
|
.then(frames => Alloy.Collections.frames.reset(frames))
|
|
138
138
|
```
|
|
139
139
|
|
|
140
|
-
## Controller
|
|
140
|
+
## Controller rules
|
|
141
141
|
|
|
142
142
|
**DO:**
|
|
143
143
|
- Define styles in TSS files (per-controller + `app.tss` for global).
|
|
@@ -152,9 +152,9 @@ api.getFrames()
|
|
|
152
152
|
- Contain heavy business logic.
|
|
153
153
|
- Call native modules directly (use a service wrapper).
|
|
154
154
|
|
|
155
|
-
## Navigation &
|
|
155
|
+
## Navigation & cleanup pattern
|
|
156
156
|
|
|
157
|
-
### Automatic
|
|
157
|
+
### Automatic cleanup with controllerautocleanup
|
|
158
158
|
|
|
159
159
|
For automatic controller cleanup without code changes, use the ControllerAutoCleanup utility.
|
|
160
160
|
|
|
@@ -187,14 +187,14 @@ Alloy.Collections.frames = new Backbone.Collection()
|
|
|
187
187
|
|
|
188
188
|
See [ControllerAutoCleanup.js](../assets/ControllerAutoCleanup.js) for the complete source code.
|
|
189
189
|
|
|
190
|
-
## i18n and
|
|
190
|
+
## i18n and accessibility rules
|
|
191
191
|
|
|
192
192
|
- All static text must use `L('key')`.
|
|
193
193
|
- All interactive elements must have `accessibilityLabel`.
|
|
194
194
|
- Use `lib/helpers/i18n.js` for strings that require logic (e.g., "You have 5 messages").
|
|
195
195
|
- Use **TSS platform modifiers** (`[platform=ios]`, `[platform=android]`) for platform-specific design instead of conditional code.
|
|
196
196
|
|
|
197
|
-
## Widget
|
|
197
|
+
## Widget structure
|
|
198
198
|
|
|
199
199
|
Widgets are self-contained, reusable components used in 3+ places across the app.
|
|
200
200
|
|
|
@@ -210,7 +210,7 @@ app/widgets/
|
|
|
210
210
|
└── widget.json # Widget manifest
|
|
211
211
|
```
|
|
212
212
|
|
|
213
|
-
### widget.json
|
|
213
|
+
### widget.json configuration
|
|
214
214
|
```json
|
|
215
215
|
{
|
|
216
216
|
"id": "com.app.loadingOverlay",
|
|
@@ -227,7 +227,7 @@ app/widgets/
|
|
|
227
227
|
}
|
|
228
228
|
```
|
|
229
229
|
|
|
230
|
-
### Widget
|
|
230
|
+
### Widget view (widget.xml)
|
|
231
231
|
```xml
|
|
232
232
|
<Alloy>
|
|
233
233
|
<View id="container">
|
|
@@ -247,7 +247,7 @@ app/widgets/
|
|
|
247
247
|
"#messageLabel": { left: 16, right: 16, top: 16, font: { fontSize: 14 }, color: '#4b5563' }
|
|
248
248
|
```
|
|
249
249
|
|
|
250
|
-
### Widget
|
|
250
|
+
### Widget controller (widget.js)
|
|
251
251
|
```javascript
|
|
252
252
|
// Widget controller receives args via $.args
|
|
253
253
|
const args = $.args || {}
|
|
@@ -279,7 +279,7 @@ $.cleanup = () => {
|
|
|
279
279
|
}
|
|
280
280
|
```
|
|
281
281
|
|
|
282
|
-
### Using
|
|
282
|
+
### Using widgets
|
|
283
283
|
```xml
|
|
284
284
|
<!-- In any view -->
|
|
285
285
|
<Alloy>
|
|
@@ -307,7 +307,7 @@ const loadData = () => {
|
|
|
307
307
|
Widgets have their own `styles/widget.tss` file. Define all widget-specific styles there to keep them self-contained and portable.
|
|
308
308
|
:::
|
|
309
309
|
|
|
310
|
-
### Widget ↔
|
|
310
|
+
### Widget ↔ controller communication
|
|
311
311
|
|
|
312
312
|
**Pattern 1: Public methods on $**
|
|
313
313
|
|
|
@@ -369,7 +369,7 @@ function cleanup() {
|
|
|
369
369
|
}
|
|
370
370
|
```
|
|
371
371
|
|
|
372
|
-
### Widget with
|
|
372
|
+
### Widget with internal state
|
|
373
373
|
|
|
374
374
|
```javascript
|
|
375
375
|
// widgets/counter/controllers/widget.js
|
|
@@ -414,7 +414,7 @@ $.cleanup = () => {
|
|
|
414
414
|
render()
|
|
415
415
|
```
|
|
416
416
|
|
|
417
|
-
### When to
|
|
417
|
+
### When to use widget vs require
|
|
418
418
|
|
|
419
419
|
| Use `<Widget>` when | Use `<Require>` when |
|
|
420
420
|
| ------------------------------------- | ------------------------------- |
|
|
@@ -424,7 +424,7 @@ render()
|
|
|
424
424
|
| Could be extracted to another project | Specific to this app |
|
|
425
425
|
| Needs its own `widget.json` manifest | Lightweight, no manifest needed |
|
|
426
426
|
|
|
427
|
-
## config.json
|
|
427
|
+
## config.json reference
|
|
428
428
|
|
|
429
429
|
The `app/config.json` file configures Alloy compilation and runtime behavior.
|
|
430
430
|
|
|
@@ -463,7 +463,7 @@ The `app/config.json` file configures Alloy compilation and runtime behavior.
|
|
|
463
463
|
}
|
|
464
464
|
```
|
|
465
465
|
|
|
466
|
-
### Accessing
|
|
466
|
+
### Accessing config values
|
|
467
467
|
```javascript
|
|
468
468
|
// In any controller or lib file
|
|
469
469
|
const apiUrl = Alloy.CFG.apiUrl
|
|
@@ -476,7 +476,7 @@ if (Alloy.CFG.debug) {
|
|
|
476
476
|
}
|
|
477
477
|
```
|
|
478
478
|
|
|
479
|
-
###
|
|
479
|
+
### Main configuration options
|
|
480
480
|
|
|
481
481
|
| Property | Description |
|
|
482
482
|
| -------------- | ----------------------------------------- |
|