parse2plone 0.9.4

Warning

This is a Buildout recipe for use with Plone; by itself it does nothing. If you do not know what Plone is, please see: http://plone.org. If you do not know what Buildout is, please see: http://www.buildout.org/.

Getting started

Because it drives the author nuts whenever he has to dig for a recipe’s options, here are this recipe’s options:

[import]
recipe = parse2plone

# core features
path = /Plone
illegal_chars = _ .
html_extensions = html
image_extensions = gif jpg jpeg png
file_extensions = mp3
target_tags = a div h1 h2 p

# additional bells & whistles
force = false
publish = false
slugify = false
rename =
typeswap =

The parameters listed above are configured with their default values. Edit these values if you would like to change the default behavior; they are (mostly) self-explanatory. Now you can just cut and paste to get started or keep reading if you would like to know more.

Explanation

Why did you create Parse2Plone when the following packages already exist:

• http://pypi.python.org/pypi/collective.transmogrifier

  • http://pypi.python.org/pypi/transmogrify.filesystem

  • http://pypi.python.org/pypi/transmogrify.htmlcontentextractor

  • http://pypi.python.org/pypi/transmogrify.webcrawler

Here are some reasons:

• Because Parse2Plone is aimed at lowering the bar for folks who don’t already know (or want to know) what a “transmogrifier blueprint” is but are able to update their buildout.cfg file; run Buildout; then run a single command all without having to think too much.

• collective.transmogrify provides a framework for creating reusable pipes (whose definitions are called blueprints). Parse2Plone provides a single, non-reusable “pipe/blueprint”.

• The author had an itch to scratch; it will be nice for him to be able to say “just go write a script” and then point to an example.

• Transmogrifier and friends appear to be “developer’s tools”, while the author wants Parse2Plone to be an “end user’s tool”.

• parse2plone in addition to its primary role as a content importer, is intended to serve as an educational tool; both for the author and consumer. Python coding best practices and how to script tasks in Plone are the aim. Forking and pull requests are encouraged.

If you are a developer looking to create repeatable migrations, you probably want to be using collective.transmogrifier. If you are an end user that just wants to see your static website in Plone, then you might want to give Parse2Plone a try.

There is also this user/contributor comment, which captures the author’s sentiment:

Parse2Plone's release was very timely as I need either this or something very
similar - and while I've no doubt I could make transmogrify do the job, it's a
lot of work for a one-shot loading of legacy pages.

                                                -Derek Broughton, Pointer
                                                 Stop Consulting, Inc.

Installation

You can install Parse2Plone by editing your buildout.cfg file like so. First add an import section:

[import]
recipe = parse2plone

Then add the import section to the list of parts:

[buildout]
...
parts =
    ...
    import

Now run bin/buildout as usual.

Execution

Now you can run Parse2Plone like this:

$ bin/plone run bin/import /path/to/files

Demonstration

If you have a site in /var/www/html that contains the following:

/var/www/html/index.html
/var/www/html/about/index.html

You should run:

$ bin/plone run bin/import /var/www/html

And the following will be created:

• http://localhost:8080/Plone/index.html

• http://localhost:8080/Plone/about/index.html

Modification

Modifying the default behavior of parse2plone is easy; just use the command line options or add parameters to your buildout.cfg file. Both approaches allow customization of the same set of options, but the command line arguments will trump any settings found in your buildout.cfg file.

[import]
recipe = parse2plone
path = /Plone/foo
html_extensions = htm
image_extensions = png
target_tags = p

$ bin/plone run bin/import /path/to/files --path=/Plone/foo

$ bin/plone run bin/import /path/to/files --html-extensions=htm

$ bin/plone run bin/import /path/to/files --image-extensions=png

$ bin/plone run bin/import /path/to/files --file-extensions=pdf

$ bin/plone run bin/import /path/to/files --target-tags=p

$ bin/plone run bin/import -h
Usage: import [options]

Options:
  -h, --help            show this help message and exit
  -p PATH, --path=PATH  Path to Plone site object or sub-folder
  --html-extensions=HTML_EXTENSIONS
                        Specify HTML file extensions
  --illegal-chars=ILLEGAL_CHARS
                        Specify characters to ignore
  --image-extensions=IMAGE_EXTENSIONS
                        Specify image file extensions
  --file-extensions=FILE_EXTENSIONS
                        Specify generic file extensions
  --target-tags=TARGET_TAGS
                        Specify HTML tags to parse
  --force               Force creation of folders
  --publish             Optionally publish newly created content
  --slugify             Optionally "slugify" content (see slugify.py)
  --rename=RENAME       Optionally rename content (see rename.py)
  --typeswap=TYPESWAP   Optionally swap content types (see typeswap.py)

$ bin/plone run bin/import /path/to/files -p /Plone/foo --html-extensions=html \
    --image-extensions=png --target-tags=p

Consternation

Here are some trouble-shooting comments/tips.

Communication

Questions, comments, or concerns? Please e-mail: aclark@aclark.net.

History