Publication¶

This section covers work organization, roles involved, and options for making scenarios accessible to end users.

Roles and responsibilities¶

In a corporate context, two distinct roles interact with ChoiceMap.

End user¶

The end user uses only the Navigator to consume scenarios. They have no access to editors and don't modify content.

Administrator¶

The administrator creates, modifies, and publishes scenarios. They have full access to all tools.

In small contexts, the same person may cover both roles. In larger organizations, roles are typically separate.

Administrator workflow¶

Working repository¶

The administrator maintains a local repository (a folder on their computer or server) with all project files:

choicemap/
├── choicemap.html    # Navigator
├── scenario-editor.html        # Scenario editor
├── theme-editor.html           # Theme editor
├── config.json                 # Configuration
├── defaults.json               # Default values
├── shared-styles.css           # Shared styles
├── scenarios/                  # Scenarios in progress
│   ├── onboarding-v1.json
│   ├── onboarding-v2.json
│   └── compliance-draft.json
├── themes/                     # Custom themes
│   └── corporate-theme.json
└── resources/                  # Attached documents
    ├── manual.pdf
    └── checklist.docx

Typical work cycle¶

1. Create or modify the scenario using scenario-editor.html
2. Customize the theme using theme-editor.html (if needed)
3. Configure config.json to point to the correct scenario and theme
4. Test by opening choicemap.html in the browser
5. Iterate until achieving the desired result
6. Publish by copying only the necessary files to the destination

Versioning¶

It's good practice to maintain scenario versions:

• keep previous versions (e.g., scenario-v1.json, scenario-v2.json)
• annotate significant changes
• use a version control system (Git) for complex projects

Preparing for publication¶

Files needed for end users¶

To publish a scenario, only these files are needed:

Do not include in publication:

• scenario-editor.html (not needed for end users)
• theme-editor.html (not needed for end users)
• shared-styles.css (used only by editors)
• Draft scenarios or test versions
• Administrator working files

Configure config.json¶

Before publishing, verify that config.json points to the correct files:

{
    "scenario": "scenario-onboarding.json",
    "theme": "corporate-theme.json",
    "showCredits": false
}

The showCredits: false option removes the footer with credits, for a cleaner appearance.

Publication destinations¶

Corporate intranet¶

For internal use, copy files to a shared folder on the corporate file server.

\\server\share\training\
├── choicemap.html
├── config.json
├── defaults.json
└── scenario-onboarding.json

Users access by directly opening the HTML file or via a link on the intranet.

Public website¶

For web publication, upload files to any static hosting:

• GitHub Pages (free)
• Netlify, Vercel (free with limitations)
• Amazon S3, Google Cloud Storage
• Traditional hosting

No PHP, database, or other server-side component support is needed.

Corporate LMS¶

To integrate into a Learning Management System:

• some LMSs support uploading HTML packages
• others allow embedding via iframe
• verify the specific LMS security policies

GitHub Pages¶

GitHub Pages is the simplest solution for publishing to the web for free.

Procedure¶

1. Create a repository on GitHub
2. Upload necessary files (only those for end users)
3. In Settings → Pages, enable publishing from main branch
4. Wait for deploy (1-2 minutes)

Resulting URL¶

https://username.github.io/repository-name/choicemap.html

Example: if the repository is training-onboarding by user company-xyz:

https://company-xyz.github.io/training-onboarding/choicemap.html

Updates¶

To update a published scenario:

1. Modify files locally
2. Upload new versions to GitHub
3. Wait for automatic rebuild

If changes don't appear immediately, force refresh (Ctrl+Shift+R) or wait a few minutes for caching.

Managing multiple scenarios¶

An organization may have different scenarios: onboarding, compliance, technical training.

Option 1: Separate folders¶

Each scenario has its own folder with all necessary files:

training/
├── onboarding/
│   ├── choicemap.html
│   ├── config.json
│   ├── defaults.json
│   └── scenario-onboarding.json
├── compliance/
│   ├── choicemap.html
│   ├── config.json
│   ├── defaults.json
│   └── scenario-compliance.json

Advantages: each scenario is independent, easy to manage and update separately.

Distinct URLs: - .../training/onboarding/choicemap.html - .../training/compliance/choicemap.html

Option 2: Shared installation¶

A single Navigator installation, multiple selectable scenarios:

training/
├── choicemap.html
├── defaults.json
├── config-onboarding.json
├── config-compliance.json
├── scenario-onboarding.json
└── scenario-compliance.json

Requires renaming the appropriate config to config.json to change scenarios, or modifying the Navigator to accept a URL parameter (advanced customization).

Embedding in other sites¶

The Navigator can be embedded in existing pages via iframe.

Basic code¶

<iframe 
    src="https://yourdomain.com/choicemap.html" 
    width="100%" 
    height="600" 
    frameborder="0">
</iframe>

Responsive version¶

<div style="position: relative; width: 100%; height: 100vh;">
    <iframe 
        src="https://yourdomain.com/choicemap.html" 
        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;" 
        frameborder="0"
        allowfullscreen>
    </iframe>
</div>

Considerations¶

• Verify any CORS restrictions if Navigator and page are on different domains
• External links open in the iframe unless using target="_blank"
• Keyboard navigation may behave differently inside an iframe

Security and access¶

ChoiceMap has no built-in authentication. Anyone with the URL can access it.

To restrict access:

• Private repository on GitHub (requires Pro account for GitHub Pages)
• Hosting on corporate server behind VPN
• Web server level authentication (basic auth, corporate SSO)
• Non-indexed URL (security through obscurity, not recommended for sensitive content)

For scenarios with confidential information, carefully evaluate infrastructure and corporate policies.