# SubredditWidgetsModeration

class `praw.models.``SubredditWidgetsModeration`(subreddit, reddit)

  Class for moderating a subreddit’s widgets.

  Get an instance of this class from `SubredditWidgets.mod`.

  Example usage:

      styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
      reddit.subreddit('learnpython').widgets.mod.add_text_area(
          'My title', '**bold text**', styles)

  Note

  To use this class’s methods, the authenticated user must be a moderator with appropriate permissions.

  `__init__`(subreddit, reddit)

    Initialize the class.

  `add_button_widget`(short_name, description, buttons, styles, **other_settings)

    Add and return a `ButtonWidget`.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - description – Markdown text to describe the widget.
    - buttons –

      A `list` of `dict`s describing buttons, as specified in Reddit docs. As of this writing, the format is:

      Each button is either a text button or an image button. A text button looks like this:

          {
            "kind": "text",
            "text": a string no longer than 30 characters,
            "url": a valid URL,
            "color": a 6-digit rgb hex color, e.g. `#AABBCC`,
            "textColor": a 6-digit rgb hex color, e.g. `#AABBCC`,
            "fillColor": a 6-digit rgb hex color, e.g. `#AABBCC`,
            "hoverState": {...}
          }

      An image button looks like this:

          {
            "kind": "image",
            "text": a string no longer than 30 characters,
            "linkUrl": a valid URL,
            "url": a valid URL of a reddit-hosted image,
            "height": an integer,
            "width": an integer,
            "hoverState": {...}
          }

      Both types of buttons have the field `hoverState`. The field does not have to be included (it is optional). If it is included, it can be one of two types: text or image. A text `hoverState` looks like this:

          {
            "kind": "text",
            "text": a string no longer than 30 characters,
            "color": a 6-digit rgb hex color, e.g. `#AABBCC`,
            "textColor": a 6-digit rgb hex color, e.g. `#AABBCC`,
            "fillColor": a 6-digit rgb hex color, e.g. `#AABBCC`
          }

      An image `hoverState` looks like this:

          {
            "kind": "image",
            "url": a valid URL of a reddit-hosted image,
            "height": an integer,
            "width": an integer
          }

      Note

      The method `upload_image()` can be used to upload images to Reddit for a `url` field that holds a Reddit-hosted image.

      Note

      An image `hoverState` may be paired with a text widget, and a text `hoverState` may be paired with an image widget.

    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        my_image = widget_moderation.upload_image('/path/to/pic.jpg')
        buttons = [
            {
                'kind': 'text',
                'text': 'View source',
                'url': 'https://github.com/praw-dev/praw',
                'color': '#FF0000',
                'textColor': '#00FF00',
                'fillColor': '#0000FF',
                'hoverState': {
                    'kind': 'text',
                    'text': 'ecruos weiV',
                    'color': '#FFFFFF',
                    'textColor': '#000000',
                    'fillColor': '#0000FF'
                }
            },
            {
                'kind': 'image',
                'text': 'View documentation',
                'linkUrl': 'https://praw.readthedocs.io',
                'url': my_image,
                'height': 200,
                'width': 200,
                'hoverState': {
                    'kind': 'image',
                    'url': my_image,
                    'height': 200,
                    'width': 200
                }
            }
        ]
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        new_widget = widget_moderation.add_button_widget(
            'Things to click', 'Click some of these *cool* links!',
            buttons, styles)

  `add_calendar`(short_name, google_calendar_id, requires_sync, configuration, styles, **other_settings)

    Add and return a `Calendar` widget.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - google_calendar_id – An email-style calendar ID. To share a Google Calendar, make it public, then find the “Calendar ID.”
    - requires_sync – A `bool`.
    - configuration –

      A `dict` as specified in Reddit docs. Example:

          {'numEvents': 10,
           'showDate': True,
           'showDescription': False,
           'showLocation': False,
           'showTime': True,
           'showTitle': True}

    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        config = {'numEvents': 10,
                  'showDate': True,
                  'showDescription': False,
                  'showLocation': False,
                  'showTime': True,
                  'showTitle': True}
        cal_id = 'y6nm89jy427drk8l71w75w9wjn@group.calendar.google.com'
        new_widget = widget_moderation.add_calendar('Upcoming Events',
                                                    cal_id, True,
                                                    config, styles)

  `add_community_list`(short_name, data, styles, **other_settings)

    Add and return a `CommunityList` widget.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - data – A `list` of subreddits. Subreddits can be represented as `str` (e.g. the string `'redditdev'`) or as `Subreddit` (e.g. `reddit.subreddit('redditdev')`). These types may be mixed within the list.
    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        subreddits = ['learnpython', reddit.subreddit('redditdev')]
        new_widget = widget_moderation.add_community_list('My fav subs',
                                                          subreddits,
                                                          styles)

  `add_custom_widget`(short_name, text, css, height, image_data, styles, **other_settings)

    Add and return a `CustomWidget`.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - text – The Markdown text displayed in the widget.
    - css –

      The CSS for the widget, no longer than 100000 characters.

      Note

      As of this writing, Reddit will not accept empty CSS. If you wish to create a custom widget without CSS, consider using `'/**/'` (an empty comment) as your CSS.

    - height – The height of the widget, between 50 and 500.
    - image_data –

      A `list` of `dict`s as specified in Reddit docs. Each `dict` represents an image and has the key `'url'` which maps to the URL of an image hosted on Reddit’s servers. Images should be uploaded using `upload_image()`. Example:

          [{'url': 'https://some.link',  # from upload_image()
            'width': 600, 'height': 450,
            'name': 'logo'},
           {'url': 'https://other.link',  # from upload_image()
            'width': 450, 'height': 600,
            'name': 'icon'}]

    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        image_paths = ['/path/to/image1.jpg', '/path/to/image2.png']
        image_urls = [widget_moderation.upload_image(img_path)
                      for img_path in image_paths]
        image_dicts = [{'width': 600, 'height': 450, 'name': 'logo',
                        'url': image_urls[0]},
                       {'width': 450, 'height': 600, 'name': 'icon',
                        'url': image_urls[1]}]
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        new_widget = widget_moderation.add_custom_widget('My widget',
                                                        '# Hello world!',
                                                        '/**/', 200,
                                                        image_dicts, styles)

  `add_image_widget`(short_name, data, styles, **other_settings)

    Add and return an `ImageWidget`.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - data –

      A `list` of `dict`s as specified in Reddit docs. Each `dict` has the key `'url'` which maps to the URL of an image hosted on Reddit’s servers. Images should be uploaded using `upload_image()`. Example:

          [{'url': 'https://some.link',  # from upload_image()
            'width': 600, 'height': 450,
            'linkUrl': 'https://github.com/praw-dev/praw'},
           {'url': 'https://other.link',  # from upload_image()
            'width': 450, 'height': 600,
            'linkUrl': 'https://praw.readthedocs.io'}]

    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        image_paths = ['/path/to/image1.jpg', '/path/to/image2.png']
        image_dicts = [{'width': 600, 'height': 450, 'linkUrl': '',
                        'url': widget_moderation.upload_image(img_path)}
                       for img_path in image_paths]
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        new_widget = widget_moderation.add_image_widget('My cool pictures',
                                                        image_dicts, styles)

  `add_menu`(data, **other_settings)

    Add and return a `Menu` widget.

    Parameters:

    data –

    A `list` of `dict`s describing menu contents, as specified in Reddit docs. As of this writing, the format is:

        [
          {
            "text": a string no longer than 20 characters,
            "url": a valid URL
          },

          OR

          {
            "children": [
              {
                 "text": a string no longer than 20 characters,
                 "url": a valid URL,
              },
              ...
             ],
            "text": a string no longer than 20 characters,
          },
          ...
        ]

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        menu_contents = [
            {'text': 'My homepage', 'url': 'https://example.com'},
            {'text': 'Python packages',
             'children': [
                 {'text': 'PRAW', 'url': 'https://praw.readthedocs.io/'},
                 {'text': 'requests', 'url': 'http://python-requests.org'}
             ]},
            {'text': 'Reddit homepage', 'url': 'https://reddit.com'}
        ]
        new_widget = widget_moderation.add_menu(menu_contents)

  `add_post_flair_widget`(short_name, display, order, styles, **other_settings)

    Add and return a `PostFlairWidget`.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - display – Display style. Either `'cloud'` or `'list'`.
    - order –

      A `list` of flair template IDs. You can get all flair template IDs in a subreddit with:

          flairs = [f['id'] for f in subreddit.flair.link_templates]

    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        subreddit = reddit.subreddit('mysub')
        widget_moderation = subreddit.widgets.mod
        flairs = [f['id'] for f in subreddit.flair.link_templates]
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        new_widget = widget_moderation.add_post_flair_widget('Some flairs',
                                                             'list',
                                                             flairs, styles)

  `add_text_area`(short_name, text, styles, **other_settings)

    Add and return a `TextArea` widget.

    Parameters:

    - short_name – A name for the widget, no longer than 30 characters.
    - text – The Markdown text displayed in the widget.
    - styles – A `dict` with keys `backgroundColor` and `headerColor`, and values of hex colors. For example, `{'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}`.

    Example usage:

        widget_moderation = reddit.subreddit('mysub').widgets.mod
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        new_widget = widget_moderation.add_text_area('My cool title',
                                                     '*Hello* **world**!',
                                                     styles)

  `reorder`(new_order, section='sidebar')

    Reorder the widgets.

    Parameters:

    - new_order – A list of widgets. Represented as a `list` that contains `Widget` objects, or widget IDs as strings. These types may be mixed.
    - section – The section to reorder. (default: `'sidebar'`)

    Example usage:

        widgets = reddit.subreddit('mysub').widgets
        order = list(widgets.sidebar)
        order.reverse()
        widgets.mod.reorder(order)

  `upload_image`(file_path)

    Upload an image to Reddit and get the URL.

    Parameters: | file_path – The path to the local file.
    Returns: | The URL of the uploaded image as a `str`.

    This method is used to upload images for widgets. For example, it can be used in conjunction with `add_image_widget()`, `add_custom_widget()`, and `add_button_widget()`.

    Example usage:

        my_sub = reddit.subreddit('my_sub')
        image_url = my_sub.widgets.mod.upload_image('/path/to/image.jpg')
        images = [{'width': 300, 'height': 300,
                   'url': image_url, 'linkUrl': ''}]
        styles = {'backgroundColor': '#FFFF66', 'headerColor': '#3333EE'}
        my_sub.widgets.mod.add_image_widget('My cool pictures', images,
                                            styles)