🚀 EzyPlatform Toolkit – Bootstrap & Sync for EzyArticle
Official Visual Studio Code extension for bootstrapping, synchronizing, previewing, and publishing EzyArticle projects directly from your local workspace to an EzyPlatform server.
Designed for structured enterprise CMS workflows and scalable content management.
✨ Key Features
- ⚡ Project Bootstrap for EzyArticle
- 🔐 Secure Environment Authentication
- 🔄 Two-way Synchronization (Local ↔ Server) for pages, posts, page fragments, mail templates, content templates, terms, and i18n messages
- 🚀 One-click Publish
- 👁 Live Preview for pages, posts, mail templates, and content templates
- 🔗 Copy Admin/Web URLs for pages, posts, and media
- 🖼 Media Upload with Auto Sync
- 👀 Media Sync, Public/Unpublic Toggle
- ⏱ Access Token Auto-Renew Scheduler
🏗 Project Bootstrap
When right-clicking inside the workspace and environment.json does not exist, a command:
Initialize EzyArticle Project
will generate:
[
{
"name": "production",
"default": true,
"admin_url": "<EzyPlatform Production Admin URL>",
"admin_access_token": "<Admin Access Token>"
},
{
"name": "beta",
"admin_url": "<EzyPlatform Beta Admin URL>",
"admin_access_token": "<Admin Access Token>",
"notes": "Optional environment"
}
]
And scaffold the project structure:
api/v1/media/.gitignore
pages/example-page/
content.html
head.html
foot.html
meta.json
🔐 Authentication & Token Management
The extension validates:
admin_urladmin_access_token
If missing or invalid, guided error messages will appear, including direct links to ${admin_url}/admins/me to retrieve or refresh the access token.
Automatic Token Renewal
The extension:
- Checks every 5 minutes for valid credentials.
- Fetches cookie-based access token.
- Schedules auto-renew 15 minutes before expiration.
- Handles failures gracefully without interrupting workflow.
🔄 Synchronization Features
Sync Page Fragments (Server → Local)
Fetch fragments via:
/ezyarticle/api/v1/pages/fragments
Generate structure:
page-fragments/
<page-name>/
<fragment-name>/
content.html
head.html
foot.html
Sync Individual Fragment Files / Folders
Supports:
- content.html / content..html
- head.html / head..html
- foot.html / foot..html
- meta.json / meta..json
Maps:
| File |
Server Field |
| content |
content |
| head |
additionalHead |
| foot |
additionalFoot |
| meta |
structured JSON |
Available from the context menu on a fragment file/folder or the active editor. Multiple selected files are synced sequentially.
Sync Pages & Posts (Server → Local)
API:
/ezyarticle/api/v1/post-by-slug/{slug}
Automatically maps:
- content
- title
- summary
- pageType / postType
- contentType
- status
- priority
- publishedAt (rendered as
yyyy-MM-dd HH:mm:ss, omitted when the server has no publish time)
- password (the hash stored on the server; a value already present in
meta.json is kept as is)
- metadata
- featuredImageId
- terms (via
/ezyarticle/api/v1/post-by-slug/{slug}/terms)
Keep the synced password untouched to preserve the current password, replace it with plain text to set a new one, or remove the field to clear it on the next save.
Available from the context menu on a page/post file, folder, or the active editor. Multiple selected files are synced sequentially.
⬆ Sync Local Changes to Server
When saving supported files (content, head, foot, meta, including .<lang>. variants), the extension:
- Detects language variants
- Extracts metadata
- Resolves slug or fragment info
- Converts
publishedAt from yyyy-MM-dd HH:mm:ss to a timestamp and sends password as is
- Sends structured payload
- Updates
meta.json with response data (status, contentType)
meta.json carries no id field — content is identified by its folder name (the slug) or, for page fragments, by its page_name/fragment_name path. Any leftover id is removed on the next save.
🚀 Publish to Server
Right-click a page, post, or page fragment file/folder → Publish Content to Server
Calls:
/ezyarticle/api/v1/posts/save-simply?publish=true
Ensures:
- Language-aware content resolution
- Metadata integrity
- Auto-creates missing
meta.json / content.html with sensible defaults
- Safe overwrite confirmation
👁 Preview Page / Post
Right-click a page or post file/folder → Preview Page / Preview Post
Triggers:
<admin_url>/ezyarticle/pages/{slug}/preview[?lang=<language>]
<admin_url>/ezyarticle/posts/{slug}/preview[?lang=<language>]
Automatically saves files before opening the browser.
🔗 Get Page / Post URLs
Right-click a page or post file/folder to copy URLs to the clipboard:
- Get Page Admin URL / Get Post Admin URL →
<admin_url>/ezyarticle/pages|posts/{slug}/view[?lang=<language>]
- Get Page Web URL →
<web_url>/{slug}[?lang=<language>] (web_url is fetched from /api/v1/settings/web-url)
Files are saved automatically before the URL is generated.
When adding files to:
/api/v1/media
that have content (files that are empty, contain only whitespace, or whose content is exactly {"token":"invalid"} are skipped), the extension:
Checks existence:
/api/v1/media/{file_name}/contains
- If exists → Prompts for confirmation (overwriting may lose the server content), then replaces on confirm
- If not → Add new media
Supports progress tracking and upload feedback.
Right-click a media file → Sync Media to download and overwrite the local file via /api/v1/media/{name}.
Right-click the api/v1/media folder → Download Media From Link. A link already in your clipboard is offered in a dialog (Download / Enter another link); otherwise you are asked to type one.
- Links to this environment —
<admin_url>/api/v1/media/<file_name> (fetched with the access token) or <web_url>/api/v1/media/<file_name> (fetched without one, web_url coming from /api/v1/settings/web-url). Saved as <file_name>; already on the server, so nothing is uploaded back.
- External links — verified to point at a real file rather than a web page, named from
Content-Disposition or the link's last path segment (you're asked to type a name when neither works), then uploaded to your server automatically, with the usual overwrite confirmation when that media already exists.
Existing local files are never overwritten without asking. A file inside api/v1/media whose content is only a link to this environment's media is resolved the same way on save.
- Get Media Admin URL →
<admin_url>/api/v1/media/<file_name>
- Get Media Web URL →
<web_url>/api/v1/media/<file_name>
Right-click a media file to toggle its visibility via /api/v1/media/{name}/public and /api/v1/media/{name}/unpublic.
📧 Mail Templates
Under mail-templates/<template_name>/:
- Sync from server — maps
title.html ← titleTemplate, content.html ← contentTemplate, meta.json ← contentType/status/parameters.
- Publish to server via
/ezymail/api/v1/templates/add-or-update.
- Preview — opens
<admin_url>/ezyamil/templates/preview?templateName=<name>¶meters=[...].
📝 Content Templates
Under content-templates/<template_type>/<template_name>/:
- Sync from server — maps
title.html, content.html, meta.json from /ezysupport/api/v1/templates/{type}/{name}.
- Publish to server via
/ezysupport/api/v1/templates/add-or-update.
- Preview — opens
<admin_url>/ezysupport/templates/preview?templateType=<type>&templateName=<name>¶meters=[...].
🌐 I18n Messages
Under admin/messages/ or web/messages/, supports messages.properties and messages_<lang>.properties.
- Publish to server via
PUT /ezysupport/api/v1/<target>/messages.
🏷 Terms
Under terms/<term_type>/<term_slug>/:
- Sync from server — maps
description.txt ← description, meta.json ← name/featuredImageName/displayOrder/status.
- Publish to server via
PUT /ezyarticle/api/v1/terms/add-or-update.
🎯 Who Is This For?
- EzyPlatform developers
- EzyArticle CMS teams
- Enterprise content teams
- Structured content workflows
- Multi-language publishing environments
🧠 Why Use This Extension?
Instead of manual API calls and folder management, this extension provides:
- Consistent project structure
- Reliable token lifecycle management
- Bi-directional synchronization across pages, posts, fragments, mail templates, content templates, terms, and i18n messages
- Reduced deployment errors
- Faster onboarding for new team members
📬 Support & Resources
License
This extension is distributed under the MIT License; see LICENSE for details.
Built and maintained by the EzyPlatform team at YoungMonkeys.
