# 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. For 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, description='', **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"}`.

      - description – A `str` containing Markdown (default: `""`).

    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, "description"
        )

  `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()`.

        For 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()`.

        For 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)