Metadata-Version: 2.4
Name: kotti2-iframe
Version: 3.0.3
Summary: Kotti plugin for embedding external content via iframe
Home-page: https://github.com/skywalk163/kotti_py312
Author: Kotti Community
Author-email: kotti@example.com
License: BSD
Keywords: kotti iframe embed playground cms
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Pyramid
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: License :: OSI Approved :: BSD License
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: Kotti2>=3.0.0
Provides-Extra: testing
Requires-Dist: pytest<9.0.0,>=7.0.0; extra == "testing"
Requires-Dist: pytest-cov>=4.0.0; extra == "testing"
Requires-Dist: WebTest>=3.0.0; extra == "testing"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

kotti-iframe
=============

This is an extension to Kotti2 CMS that allows you to embed external web pages
and online playgrounds using HTML iframes.

**This package is only compatible with Kotti2 version 3.0.0 and later.**

Use Cases
---------

- Embed online code playgrounds (Repl.it, CodePen, JSFiddle, etc.)
- Embed documentation pages
- Embed interactive tools and applications
- Create language learning pages with live examples

Features
--------

- **Simple Integration**: Add iframe content through Kotti's admin interface
- **Flexible Sizing**: Configure width and height using CSS values
- **Security Controls**: Sandbox attributes for secure embedding
- **External Links**: Optional button to open content in new tab
- **Embed-Only View**: Minimal view for AJAX or custom integration

Quick Start (5 Minutes)
-----------------------

1. Install the package::

    pip install kotti-iframe

2. Add to your Kotti configuration file (e.g., ``development.ini``)::

    kotti.configurators =
        kotti_iframe.kotti_configure

3. Initialize the database (if starting fresh)::

    python init_db.py development.ini

4. Start the server::

    pserve development.ini

5. Log in to your Kotti site (default: admin / qwerty)

6. Navigate to a Document and click "Add" → "Iframe Content"

Installation
------------

Prerequisites
~~~~~~~~~~~~~

- Python 3.10 or higher
- Kotti2 >= 3.0.0

Install from PyPI
~~~~~~~~~~~~~~~~~

::

    pip install kotti-iframe

Install from Source
~~~~~~~~~~~~~~~~~~~

::

    git clone https://gitcode.com/skywalk163/kotti-iframe.git
    cd kotti-iframe
    pip install -e .

Configuration
-------------

Basic Configuration
~~~~~~~~~~~~~~~~~~~

Add the configurator to your INI file::

    kotti.configurators =
        kotti_iframe.kotti_configure

This will:

- Register the IframeContent type
- Add it to the list of addable content types
- Configure the database migrations

Full Example Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~

Here's a complete ``development.ini`` example::

    [app:kotti_iframe]
    use = egg:kotti

    pyramid.reload_templates = true
    pyramid.debug_templates = true
    pyramid.includes =
        pyramid_debugtoolbar
        pyramid_tm

    sqlalchemy.url = sqlite:///%(here)s/kotti_iframe.db

    kotti.configurators =
        kotti_iframe.kotti_configure
    kotti.site_title = My Kotti Site
    kotti.secret = your-secret-password-here

    [server:main]
    use = egg:waitress#main
    port = 5001

Database Initialization
-----------------------

For a Fresh Installation
~~~~~~~~~~~~~~~~~~~~~~~~

If you're starting with a new database, run::

    python init_db.py development.ini

This will:

1. Create all necessary database tables
2. Create the root Document
3. Create the admin user

For Existing Kotti Installations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you already have a Kotti database, run the migration::

    alembic -c development.ini upgrade head

Usage
-----

Adding Iframe Content
~~~~~~~~~~~~~~~~~~~~~

1. Log in to your Kotti site as admin
2. Navigate to the Document where you want to add the iframe
3. Click the "Add" button in the editor bar
4. Select "Iframe Content" from the dropdown
5. Fill in the form:

   - **Title**: Display title for the iframe
   - **Description**: Optional description
   - **Iframe URL**: The URL to embed (required)
   - **External URL**: Link to open in new tab (defaults to iframe URL)
   - **Width**: CSS width value (default: "100%")
   - **Height**: CSS height value (default: "600px")
   - **Allow Fullscreen**: Enable fullscreen mode (default: yes)
   - **Show External Link**: Show "Open in New Tab" button (default: yes)
   - **Container CSS Class**: Additional CSS classes for styling

6. Click "Save"

Viewing Iframe Content
~~~~~~~~~~~~~~~~~~~~~~

- **Default View**: Shows the iframe with title, description, and optional external link button
- **Embed View**: Access via ``/embed`` URL for minimal display (just the iframe)

Example Playgrounds
-------------------

Here are some popular playgrounds you can embed:

Repl.it (Python):
    https://replit.com/@username/repl-name?embed=true

CodePen:
    https://codepen.io/username/embed/pen-id

JSFiddle:
    https://jsfiddle.net/username/id/embedded/

Google Colab:
    https://colab.research.google.com/drive/id

StackBlitz:
    https://stackblitz.com/edit/project-id?embed=1

Security Considerations
-----------------------

The iframe uses sandbox attributes to restrict what the embedded content
can do. By default, the sandbox allows:

- **allow-scripts**: Execute JavaScript
- **allow-same-origin**: Access same-origin resources
- **allow-forms**: Submit forms
- **allow-popups**: Open popup windows

Custom Sandbox Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can customize sandbox restrictions by setting the ``sandbox_attributes``
field when creating or editing IframeContent. For example::

    ["allow-scripts", "allow-forms"]

This would allow scripts and forms, but block same-origin access and popups.

For maximum security when embedding untrusted content::

    []

This applies the most restrictive sandbox (no permissions).

Development
-----------

Running Tests
~~~~~~~~~~~~~

::

    pip install -e ".[testing]"
    pytest kotti_iframe/tests/

Building the Package
~~~~~~~~~~~~~~~~~~~~

::

    python -m build

Contributing
~~~~~~~~~~~~

Contributions are welcome! Please submit pull requests or issues at:
https://gitcode.com/skywalk163/kotti-iframe

License
-------

MIT License. See LICENSE.txt for details.

Authors
-------

- Kotti Community

Changelog
---------

See CHANGES.rst for version history.


Changes
=======

3.0.3 (2026-06-06)
-------------------

- Complete rewrite using Kotti's standard form system
- IframeContent type with configurable width, height, sandbox attributes
- View and embed templates
- External link button support
- Full add/edit forms using ContentSchema, AddFormView, EditFormView
- Database migration support (alembic)
- Comprehensive test suite (12 tests, 100% pass rate)
- Database initialization script (init_db.py)
- Complete documentation for beginners (GETTING_STARTED.md)

0.1.0 (2026-06-05)
------------------

- Initial release
- Basic IframeContent type
