Usage — django-markupmirror 0.1a2 documentation

### Navigation

- index
- modules |
- next |
- previous |
- django-markupmirror 0.1a2 documentation »

# Usage

## Markup-Types

django-markupmirror comes with five default markup types (or converters). You Can create and register your own converters and unregister the default ones if you prefer.

### Default Markup Types

The markup-types available by default are:

`plaintext`
  class `markupmirror.markup.plaintext.` `PlainTextMarkup`

    Markup transformer for plain-text content.

    This uses Django’s `urlize` and `linebreaks` utitlies to convert URLs in the text to clickable links and linebreaks to `<p>` and `<br />` elements respectively.

`html`
  class `markupmirror.markup.html.` `HtmlMarkup`

    Markup pseudo-transformer for HTML content.

    This does not transform anything and thus is potentially harmful. Use with care.

`markdown`
  class `markupmirror.markup.markdown_.` `MarkdownMarkup`

    Markup transformer for Markdown content.

`restructuredtext`
  class `markupmirror.markup.restructuredtext.` `ReStructuredTextMarkup`

    Markup transformer for reStructuredText content.

`textile`
  class `markupmirror.markup.textile_.` `TextileMarkup`

    Markup transformer for Textile content.

### The Markup Pool

The markup pool is the main access point to markup converters. They are registered with the pool, and retrieved from it.

`markupmirror.markup.base.` `markup_pool`

  Instance of `MarkupPool` for public use.

class `markupmirror.markup.base.` `MarkupPool`

  Pool for markup converters.

  Each markup class, subclassing `markupmirror.markup.base.BaseMarkup`, must register to this pool using `register_markup` defined below.

  `register_markup`(markup)

    Registers a markup converter class.

    `markup` must be a subclass of `BaseMarkup` and may not be registered already.

  `unregister_markup`(markup_name)

    Unregisters a markup converter with the name `markup_name`. Fails silently if no converter was registered by that name.

    Alternatively you can also use the `del` operator:

        del markup_pool['restructuredtext']

  `has_markup`(markup_name)

    Tests if a markup converter with the name `markup_name` is already registered with the markup pool.

    Alternatively you can also use the `in` operator, like with a dictionary:

        if 'restructuredtext' in markup_pool:
            pass

  `get_markup`(markup_name)

    Returns one markup converter by name. Raises `KeyError` if no converter was registered by `markup_name`.

    Alternatively you can also use the `[]` accessor, like with a dictionary:

        markup = markup_pool['restructuredtext']

### Create your own Markup Type

You can easily create your own markup converters for any purpose. The converter only needs to inherit from `BaseMarkup` and implement the `convert` method.

class `markupmirror.markup.base.` `BaseMarkup`

  Basic interface for markup converter classes.

  An example converter could look like this:

      class ExampleMarkup(BaseMarkup):

          def convert(self, markup):
              return markup.replace("example", "markup")

  classmethod `get_name`()

    Returns lowercase markup name, without the “Markup” part.

    Class naming convention is `<Markup-Type>Markup`.

  `convert`(markup)

    Main conversion method. Must be implemented in subclasses.

  `before_convert`(markup)

    Called before `convert`. Can be used to separate the main conversion through a third-party library (e.g. Markdown) from additional logic.

  `after_convert`(markup)

    Called after `convert`. Similar to `before_convert`.

  `__call__`(markup)

    Main entry point. Calls `before_convert`, `convert` and `after_convert` in that order.

### Register and unregister Markup Types

The default markup types provided by django-markupmirror are registered during initialization. If you want to remove any of these, you can use the `MarkupPool.unregister_markup` method:

    from markupmirror.markup.base import markup_pool

    markup_pool.unregister_markup('plaintext')  # is equal to
    del markup_pool['textile']

To register new markup converters, pass the markup class to the `MarkupPool.register_markup` method:

    from markupmirror.markup.base import markup_pool, BaseMarkup

    class ExampleMarkup(BaseMarkup):

        def convert(self, markup):
            return markup.replace("markup", "example")

    markup_pool.register_markup(ExampleMarkup)

This would make the `ExampleMarkup` converter available through the key `example`, derived from its class name:

    example_markup = markup_pool['example']

## Using the `MarkupMirrorField`

After you have configured markupmirror in your settings and added your custom markup converters, the only thing left to do is to use the `MarkupMirrorField` in your models.

A field with fixed markup type would have to provide a `markup_type`:

    from django.db import models
    from markupmirror.fields import MarkupMirrorFields

    class MyModel(models.Model):
        content = MarkupMirrorField(markup_type='markdown')

To provide a selectbox for the users to select the content’s markup type manually, use `default_markup_type` instead:

    class MyModel(models.Model):
        content = MarkupMirrorField(default_markup_type='plaintext')

If you provide neither `markup_type` nor `default_markup_type`, the `MARKUPMIRROR_DEFAULT_MARKUP_TYPE` setting will be used as default.

For reference, see the `MarkupMirrorField` and `Markup` classes:

class `markupmirror.fields.` `MarkupMirrorField`(verbose_name=None, name=None, markup_type=None, default_markup_type=None, escape_html=False, **kwargs)

  Field to store markup content.

  The `MarkupMirrorField` adds three fields to the model it is used in.

  - One field for the raw markup content (`<field_name>`).
  - One field for the rendered HTML content (`<field_name>_rendered`).
  - One field that specifies the markup type (`<field_name>_markup_type`).

  The field can be used with a fixed `markup_type` or a `default_markup_type`, which displays an additional selection widget for the available markup types. However, only one of `markup_type` and `default_markup_type` can be provided.

  If neither is provided, the setting `MARKUPMIRROR_DEFAULT_MARKUP_TYPE` is used as `default_markup_type` instead.

class `markupmirror.fields.` `Markup`(instance, field_name, rendered_field_name, markup_type_field_name)

  Wrapper class for markup content output.

  Stores the names of the associated field, the rendered field and the markup_type field to make assignment possible.

  When accessing the value of a `MarkupField`, a `Markup` instance will be returned. This provides a few methods to access the raw and rendered markup, and the markup type of the saved content.

  `raw`

    The raw markup content.

  `markup_type`

    Markup type of the current markup content.

  `rendered`

    Returns the rendered markup content (read only). This is only available after `Model.save` has been called.

  `__unicode__`()

    Allows display via templates to work without safe filter. Same as `rendered`.

### Navigation

- index
- modules |
- next |
- previous |
- django-markupmirror 0.1a2 documentation »