Smart Policy Manager Plugin

1. Overview

The Smart Policies Plugin is our tool designed to organise, group, and display policy documents (PDFs, DOCX, etc.). It renders lists on the frontend using a clean, searchable interface similar to our "Smart OneDrive Selector."

Key features

• Manage a list of policy files in one place (a CPT called Policy Manager).

• Friendly display names independent from the file names.

• Copy‑paste shortcode for embedding on any page.

• Optional cross‑site sharing: publish a Policy Group from Site A, and display it on Site B using a simple per‑group key (great for MATs).

• Remote rename capability: on a consumer site you can update the displayed names, while the owner site retains full control for adding/removing files.

2. Creating a Policy Group

1. Make sure you have "Smart Policies Plugin" enabled from your website Plugins admin area.

2. Navigate to Policy Manager in the left-hand WordPress admin menu.

3. Click Add New Policy Group.

4. Enter a Title: Give your group a name (e.g., "HR Policies 2024" or "Health & Safety").

5. Visibility: By default, new groups are set to Private, as they are embedded on pages as a shortcode.

3. Managing Files

Inside the "Edit Policy Group" screen, locate the Policy Group Files box.

• Adding Files:

  1. Click the Add Files button.

  2. The WordPress Media Library will open. Select one or multiple files from your Media Library.

     1. Alternatively go to the "Upload Files" tab and upload your files.

  3. Click "Select".

  4. The files will appear in the list below. The plugin references the existing file URL (it does not re-upload the file, keeping your storage efficient).

• Renaming Files:

  • The "Display Name" defaults to the filename.

  • To change how the file looks on the frontend, type a new name in the text box under Display Name.

  • Click the Save Name button next to the field to persist the change.

• Removing Files:

  • Click the Remove button to take a file out of this specific group. This does not delete the file from your Media Library, only from this list.

4. Displaying the Policies (Shortcode)

To display the list on a page or post, copy the shortcode shown in the meta box:

[smart_policies id="123"]

Shortcode Attributes

You can customise the display using the following attributes:

Example:

ng-tns-c1983303472-20[smart_policies id="45" show_title="true" orderby="added" order="desc"]

5. Sharing a Policy Group to Other Sites

Use this when your site owns the list of policies, and you want other sites (schools in your MAT) to embed them.

1. Open your Policy Group in Admin → Policy Manager and locate the “Sharing (Cross‑site)” metabox.

2. Tick “Enable sharing this Policy Group to other sites”.

3. Leave “Shared key” blank to auto‑generate, or paste your own (keep it secret; it works like a password). Save/Update the post.

4. Copy the example consumer shortcode shown in the metabox — it looks like this:

JavaScript[smart_policies source_url="https://owner-school.example" remote_id="10095" key="YOUR_GENERATED_KEY" show_title="true"]

5. Send that shortcode (or the three values: source_url, remote_id, key) to the other site’s editor.

6. Security notes

   • The per‑group key is required for both reading and (limited) remote renaming. Keep it private.

   • You can rotate the key by entering a new one and updating the post (consumers must then update their shortcode).

6. Consuming The Policy Group On Another Site

There are two convenient ways to consume a remote group.

1. Paste the shortcode directly on the page

JavaScript[smart_policies source_url="https://owner-school.example" remote_id="10095" key="SHARED_KEY" cache_ttl="900" show_title="true"]

• Save a Cross-Site Preview

• The list will load from the owner site using the shared key.

2. Save a "Cross-site Preview" entry

• Go to: Policy Manager -> Cross-site Preview -> Add Cross-site Policy Group

• Enter the label (optional), Source URL, Remote Group ID, and Key, then Save.

• You're redirected to the Cross-site list, where you can

  • Preview the latest file list from the owner site.

  • Copy a ready-made shortcode

  • Delete the saved entry at any time

3. Caching & Performance

• The shortcode support cache_ttl (seconds). For example 900 would cache the fetched items for 15 minutes.

• You can set a timeout for retrieving the files, so that the page will load even if there is an issue with the source url using timeout.

• Editors can bypass the preview cache by using the "Refresh" button in the preview screen.

7.Frontend Features

• Live Search: A search bar at the top allows users to filter files by name instantly.

• Preview: Clicking the Eye Icon opens the document in a new tab.

8.S3 And Storage Notes

• Each site typically points to a different S3 bucket via the BUCKET environment variable.

• That’s fine: consuming a remote group doesn’t copy binaries between buckets — it simply references the file URLs (often already on a shared CDN).

• Adding files happens on the owner site using its own bucket and Media Library.

9.Troubleshooting

• “No files yet” after adding: ensure you clicked Update/Publish on the Policy Group.

• Remote site shows an error:

  • Check the source_url, remote_id, and key are correct.

  • Ensure the owner site has sharing enabled for that group.

  • Verify the site is reachable over HTTPS.

• Changes not appearing:

  • If using cache_ttl, wait until cache expires or temporarily set cache_ttl="0" to disable caching.

  • On the preview screen, use the “Refresh (bypass cache)” button.

• Can’t add/remove on consumer site:

  • This is by design. Only the owner site can add/remove. Consumer sites can rename display names if needed.

• S3 warnings in admin:

  • If you see notices about missing BUCKET, ACCESS_KEY, or SECRET_KEY, contact your Realsmart to set environment variables.

10.Shortcode Reference

Local group (same site):

text[smart_policies id="123" show_title="true" orderby="name" order="asc"]

Remote group (owner site is another domain):

text[smart_policies 
  source_url="https://owner-school.example"
  remote_id="10095"
  key="SHARED_KEY"
  cache_ttl="900"
  timeout="10"
  show_title="true"
  orderby="name"  
  order="asc"
]

Attributes

• id (number): Local Policy Group post ID.

• source_url (string): Base URL of the owner site (e.g., https://school.example).

• remote_id (number): Policy Group ID on the owner site.

• key (string): Shared key from the owner site’s Sharing box.

• cache_ttl (seconds, default 900): Cache duration. Use 0 to disable.

• timeout (seconds, default 10): Remote fetch timeout.

• show_title (true|false): Show the group title above the list.

• orderby (name|added): Sort by name or by date added.

• order (asc|desc): Sort direction.