# PPS Impact Module - Progress Tracker

## Overview
Complete rebuild of the PPS Impact module with simplified architecture using separate entity reference fields for each section instead of a single paragraph field. This approach eliminates complex form alterations and provides a cleaner implementation.

## 🎯 KEY DESIGN GOAL: Single-Screen Editorial Experience

**The module provides a complete single-screen editing experience where editors can create and edit an entire issue—including all its articles—without navigating away from the issue form.** This is accomplished through:
- **Inline Entity Form (Simple Widget)**: Create articles directly within each section field
- **Horizontal Tabs**: Organize sections into logical tabs for better screen space usage
- **Default Titles**: Pre-populated titles for Inside APTA articles
- **Real-time Progress Tracking**: Visual feedback on completion status

## Entity Architecture Status

### ✅ Architecture Design Complete
- Documented in `/docs/entity_structure/entity_structure.html`
- Uses separate entity reference fields instead of single paragraph field
- Eliminates complex widget manipulation
- Clear separation between required and optional sections

## Implementation Progress

### Phase 1: Entity & Field Configuration ⏳ 0%

#### 1.1 Content Type Configuration ❌
- [ ] Update `impact_issue` content type
- [ ] Update `impact_article` content type  
- [ ] Update `impact_archive` content type

#### 1.2 Impact Issue Fields ❌
Create field storage and field instance configs:

**Featured Articles Field**
- [ ] Create `field.storage.node.field_featured_articles.yml`
- [ ] Create `field.field.node.impact_issue.field_featured_articles.yml`
  - Type: Entity Reference → Impact Article
  - Cardinality: 4
  - Required: Yes

**Departments Articles Field**
- [ ] Create `field.storage.node.field_departments_articles.yml`
- [ ] Create `field.field.node.impact_issue.field_departments_articles.yml`
  - Type: Entity Reference → Impact Article
  - Cardinality: 3
  - Required: Yes

**Inside APTA Field**
- [ ] Create `field.storage.node.field_inside_apta.yml`
- [ ] Create `field.field.node.impact_issue.field_inside_apta.yml`
  - Type: Entity Reference → Impact Article
  - Cardinality: 3
  - Required: Yes

**Additional Sections Field**
- [ ] Create `field.storage.node.field_additional_sections.yml`
- [ ] Create `field.field.node.impact_issue.field_additional_sections.yml`
  - Type: Entity Reference → Paragraph (additional_sections)
  - Cardinality: Unlimited
  - Required: No

**Other Issue Fields**
- [ ] Update `field_issue_month` (existing)
- [ ] Update `field_issue_year` (existing)
- [ ] **Remove** `field_issue_homepage_layout` (legacy field)

#### 1.3 Impact Article Fields ❌
Create/update field configs:
- [ ] `field_article_summary` - Text (long)
- [ ] `field_article_body` - Text (formatted, long) with summary
- [ ] `field_article_author` - Entity reference → Authors taxonomy
- [ ] `field_article_bio_override` - Text (long) - Override author bio
- [ ] `field_article_category` - Entity reference → Categories taxonomy
- [ ] `field_article_keywords` - Entity reference → Keywords taxonomy
- [ ] `field_article_image` - Image field
- [ ] `field_article_published_date` - Date
- [ ] `field_article_sidebar_content` - Text (formatted, long)
- [ ] `field_article_references` - Text (long)
- [ ] **Remove** `field_article_issue` if it exists

#### 1.4 Paragraph Type Reconfiguration ❌
- [ ] Rename paragraph type from `section_articles` to `additional_sections`
- [ ] Update `paragraphs.paragraphs_type.additional_sections.yml`
- [ ] Rename field `field_section_articles` to `field_additional_articles`
- [ ] Update field configs for new naming

#### 1.5 Taxonomy Configuration ❌
**Authors Vocabulary**
- [ ] Create `taxonomy.vocabulary.authors.yml`
- [ ] Add fields:
  - [ ] `field_author_title` - Text
  - [ ] `field_author_bio` - Text (long)
  - [ ] `field_author_photo` - Image
  - [ ] `field_author_email` - Email

**Categories Vocabulary**
- [ ] Verify `taxonomy.vocabulary.impact_article_categories.yml` exists
- [ ] Create default terms via `pps_impact.install`:
```php
function pps_impact_install() {
  $categories = [
    'Practice Management',
    'Clinical Excellence', 
    'Technology & Innovation',
    'Business Development',
    'Regulatory & Compliance',
    'Patient Engagement',
    'Staff Development',
    'Marketing & Outreach',
    'Finance & Operations',
    'Leadership'
  ];
  // Create terms...
}
```

**Keywords Vocabulary**
- [ ] Verify `taxonomy.vocabulary.impact_keywords.yml` exists

### Phase 2: Form Display & Widget Configuration ⏳ 0%

#### 2.1 Entity Form Display Configuration ❌
**Impact Issue Form Display**
`core.entity_form_display.node.impact_issue.default.yml`:
- [ ] Configure field widgets:
  - `field_featured_articles`: inline_entity_form_simple
  - `field_departments_articles`: inline_entity_form_simple
  - `field_inside_apta`: inline_entity_form_simple
  - `field_additional_sections`: inline_entity_form_complex
- [ ] Set widget settings:
  ```yaml
  field_featured_articles:
    type: inline_entity_form_simple
    settings:
      form_mode: default
      override_labels: true
      label_singular: 'featured article'
      label_plural: 'featured articles'
      allow_new: true
      allow_existing: false # Always create new for issues
  ```

**Impact Article Inline Form Mode**
- [ ] Create `core.entity_form_display.node.impact_article.inline.yml`
- [ ] Include only essential fields for inline editing:
  - title
  - field_article_summary
  - field_article_author
  - field_article_category
  - field_article_body

#### 2.2 Form Alter Implementation ❌
In `pps_impact.module`:
```php
function pps_impact_form_node_impact_issue_form_alter(&$form, $form_state, $form_id) {
  _pps_impact_build_issue_tabs($form, $form_state);
}

function pps_impact_form_node_impact_issue_edit_form_alter(&$form, $form_state, $form_id) {
  _pps_impact_build_issue_tabs($form, $form_state);
}
```

#### 2.3 Tab Structure Implementation ❌
```php
function _pps_impact_build_issue_tabs(&$form, $form_state) {
  // Add library
  $form['#attached']['library'][] = 'pps_impact/issue_form_enhancements';
  
  // Create horizontal tabs container
  $form['issue_tabs'] = [
    '#type' => 'horizontal_tabs',
    '#default_tab' => 'edit-basic-info',
  ];
  
  // Tab 1: Basic Info
  $form['basic_info'] = [
    '#type' => 'details',
    '#title' => t('Basic Info'),
    '#group' => 'issue_tabs',
  ];
  // Move fields: title, field_issue_month, field_issue_year, etc.
  
  // Tab 2: Featured
  $form['featured'] = [
    '#type' => 'details', 
    '#title' => t('Featured <span class="tab-badge" data-expected="4">(0/4)</span>'),
    '#group' => 'issue_tabs',
  ];
  // Move field_featured_articles
  
  // Tab 3: Departments
  // Tab 4: Inside APTA
  // Tab 5: Additional
}
```

#### 2.4 Inside APTA Default Titles ❌
```php
// In form alter for new issues
if ($node->isNew()) {
  // Add process callbacks to set default titles
  $form['field_inside_apta']['widget'][0]['#default_value']['title'] = "Editor's Note";
  $form['field_inside_apta']['widget'][1]['#default_value']['title'] = "Membership Matters";
  $form['field_inside_apta']['widget'][2]['#default_value']['title'] = "On the Move";
}
```

### Phase 3: JavaScript & CSS Enhancements ⏳ 0%

#### 3.1 Module Library Definition ❌
`pps_impact.libraries.yml`:
```yaml
issue_form_enhancements:
  version: 1.x
  css:
    theme:
      css/issue-form-enhancements.css: {}
  js:
    js/issue-form-enhancements.js: {}
  dependencies:
    - core/jquery
    - core/drupal
    - core/once
    - core/drupal.dialog.ajax
```

#### 3.2 JavaScript Implementation ❌
`js/issue-form-enhancements.js` features:
- [ ] Count articles in each section
- [ ] Update tab badges in real-time
- [ ] Calculate overall progress percentage
- [ ] Update progress bar (0-100%)
- [ ] Highlight main featured article (first in Featured tab)
- [ ] Add keyboard shortcuts (Alt+1 through Alt+5)
- [ ] Monitor inline entity form changes

#### 3.3 CSS Styling ❌
`css/issue-form-enhancements.css`:
- [ ] Horizontal tabs layout
- [ ] Progress bar with color states:
  - Gray: 0% (empty)
  - Yellow: 1-99% (partial)
  - Green: 100% (complete)
- [ ] Tab badges styling
- [ ] Main featured article highlight (purple border/background)
- [ ] Inline entity form improvements
- [ ] Mobile responsive adjustments

### Phase 4: Validation & Business Logic ⏳ 0%

#### 4.1 Validation Implementation ❌
```php
function _pps_impact_issue_form_validate($form, FormStateInterface $form_state) {
  $warnings = [];
  
  // Check Featured articles (must be 4)
  $featured = $form_state->getValue('field_featured_articles');
  if (count($featured) < 4) {
    $warnings[] = t('Featured section needs @count more articles.', 
      ['@count' => 4 - count($featured)]);
  }
  
  // Check Departments (must be 3)
  // Check Inside APTA (must be 3)
  
  // Display as warnings (non-blocking)
  foreach ($warnings as $warning) {
    \Drupal::messenger()->addWarning($warning);
  }
}
```

#### 4.2 Form Submit Handlers ❌
- [ ] Auto-populate article dates from issue date
- [ ] Handle text format enforcement (staff_html)
- [ ] Process author creation if new

### Phase 5: Display Templates & Theming ⏳ 0%

#### 5.1 Template Files ❌
- [ ] `templates/node--impact-issue.html.twig`
  - Homepage layout with all sections
  - Featured section: 1 main + 3 secondary cards
  - Departments: 3 article cards
  - Inside APTA: 3 subsections
- [ ] `templates/node--impact-article.html.twig`
  - Article display with author info
  - Category and keywords
  - Sidebar content if present
- [ ] `templates/paragraph--additional-sections.html.twig`
  - Custom section display

#### 5.2 View Mode Configuration ❌
- [ ] Configure view modes for Impact Issue:
  - Full: Complete homepage layout
  - Teaser: Issue card for archives
- [ ] Configure view modes for Impact Article:
  - Full: Complete article view
  - Teaser: Card view for listings
  - Inline: Compact view for issue page

#### 5.3 Theme Preprocessors ❌
In `pps_impact.module`:
```php
function pps_impact_preprocess_node(&$variables) {
  if ($variables['node']->getType() == 'impact_issue') {
    // Group articles by section
    // Add section classes
  }
}
```

### Phase 6: Testing & Quality Assurance ⏳ 0%

#### 6.1 Functional Testing ❌
- [ ] Create new issue with all sections
- [ ] Test inline article creation
- [ ] Test author selection vs creation
- [ ] Verify default titles for Inside APTA
- [ ] Test validation warnings
- [ ] Test progress tracking accuracy

#### 6.2 Browser Compatibility ❌
- [ ] Chrome (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Edge (latest)
- [ ] Mobile browsers (iOS Safari, Chrome)

#### 6.3 Accessibility ❌
- [ ] Keyboard navigation through tabs
- [ ] Screen reader compatibility
- [ ] Proper ARIA labels
- [ ] Color contrast compliance

### Phase 7: Documentation & Deployment ⏳ 0%

#### 7.1 Documentation ❌
- [ ] Update README.md with installation instructions
- [ ] Create USAGE.md with editor guide
- [ ] Document theming instructions
- [ ] API documentation for hooks

#### 7.2 Configuration Export ❌
- [ ] Export all field configurations
- [ ] Export form display configurations
- [ ] Export view display configurations
- [ ] Test fresh install from configs

## Key Implementation Notes

### Why Separate Fields?
- **Simpler Implementation**: No complex widget manipulation needed
- **Better UX**: Each section is clearly defined with proper cardinality
- **Easier Validation**: Can validate each field independently
- **Cleaner JavaScript**: Direct field targeting for counts/progress

### Widget Choice Rationale
- **inline_entity_form_simple**: For article fields (cleaner inline creation)
- **inline_entity_form_complex**: Only for additional_sections paragraph (needs more control)
- **Standard select**: For categories (predefined list)
- **Autocomplete tags**: For keywords (flexible tagging)

### Form Organization Strategy
1. Use Drupal's Horizontal Tabs (better than vertical for wide forms)
2. Move secondary sidebar to bottom for more horizontal space
3. Each tab represents a logical section of the magazine
4. Progress bar provides immediate visual feedback

## Success Metrics

The implementation is successful when:
1. ✅ Editors can create complete issues without leaving the form
2. ✅ All articles are created inline with proper fields
3. ✅ Progress tracking accurately reflects completion
4. ✅ Validation ensures content requirements are met
5. ✅ The interface matches the wireframes
6. ✅ Performance is acceptable (form loads in <3 seconds)
7. ✅ The solution is maintainable and follows Drupal standards

## Current Status: Ready for Implementation

The architecture has been completely redesigned and documented. The next step is to begin Phase 1: Entity & Field Configuration, starting with creating the field storage and instance configurations for the new architecture.