196 lines
9.2 KiB
Markdown
196 lines
9.2 KiB
Markdown
# Conductor Tutorial: Build and Publish a REST Application
|
|
|
|
This tutorial uses a ready-made two-page project to introduce Conductor's main features. You will import it, run REST actions, inspect bindings, modify the visual design, save it, and publish it as a standalone application.
|
|
|
|
Allow about 25 minutes. You need an administrator account because project authoring and publishing are administrator functions.
|
|
|
|
## What you will build
|
|
|
|
The companion [Post Workshop project](../examples/project-definitions/valid-conductor-tutorial.json) uses the public JSONPlaceholder training API. It contains:
|
|
|
|
- two pages with automatic navigation and button navigation;
|
|
- Labels, Text Input, Text Area, Buttons, Status Panel, Table, and JSON Viewer components;
|
|
- a global typed variable;
|
|
- GET and POST REST actions;
|
|
- component and variable request templates;
|
|
- a page `onLoad` action and Button `onClick` actions;
|
|
- action-response bindings and a Table-selection binding; and
|
|
- public-publishing-compatible anonymous actions.
|
|
|
|
JSONPlaceholder simulates writes but does not save them. Do not enter private, confidential, or production information; tutorial field values are sent to a public third-party service. Its behavior is documented in the [JSONPlaceholder guide](https://jsonplaceholder.typicode.com/guide/).
|
|
|
|
## 1. Import the project
|
|
|
|
1. Download or open `examples/project-definitions/valid-conductor-tutorial.json` from the Conductor source bundle.
|
|
2. Sign in to Conductor as an administrator.
|
|
3. Open **JSON Editor**.
|
|
4. Select all existing JSON and replace it with the complete contents of `valid-conductor-tutorial.json`.
|
|
5. Select **Apply**.
|
|
6. Confirm the validation summary reports no errors, then open **Visual Editor**.
|
|
|
|
Applying JSON changes the in-memory project; it does not save it to the database. If Apply fails, confirm you copied the entire file and that `schemaVersion` remains `0.1.0`.
|
|
|
|
## 2. Tour the Visual Editor
|
|
|
|
The **Create a Post** page should be selected. Notice these parts of the workspace:
|
|
|
|
- The project command area shows the project name and New, Save, Load, and Preview controls.
|
|
- The page ribbon switches pages and changes page names, slugs, order, navigation visibility, and lifecycle events.
|
|
- The component palette adds controls to the active page.
|
|
- The canvas shows the application layout.
|
|
- **Selection** edits the selected component's identity, position, size, properties, appearance, and events.
|
|
|
|
Select **Post title**, **Post body**, **Create post**, and **API response** in turn. Observe how Text Input, Text Area, Button, and JSON Viewer expose different properties.
|
|
|
|
Try one harmless visual change:
|
|
|
|
1. Select the heading.
|
|
2. Change its displayed text to `My REST Post Workshop`.
|
|
3. Move or resize it on the canvas.
|
|
|
|
The dot beside the project name indicates an unsaved canonical change.
|
|
|
|
## 3. Run the POST action
|
|
|
|
1. Open **Preview**.
|
|
2. Change the post title and body if desired, using only non-sensitive tutorial text.
|
|
3. Select **Create post**.
|
|
|
|
The Status Panel should show created ID `101`, and the JSON Viewer should display the simulated response. This single interaction demonstrates:
|
|
|
|
```text
|
|
Button onClick
|
|
→ Create simulated post action
|
|
→ component and variable template interpolation
|
|
→ server-side POST request
|
|
→ response bindings
|
|
→ Status Panel and JSON Viewer runtime updates
|
|
```
|
|
|
|
Return to **JSON Editor** and notice that your Preview inputs, response, and ID were not written into the project. Preview state is intentionally ephemeral.
|
|
|
|
## 4. Inspect the action and templates
|
|
|
|
Open **Actions & Bindings**, expand **REST Actions**, and open **Create simulated post**.
|
|
|
|
The action sends `POST https://jsonplaceholder.typicode.com/posts` with a JSON content type. Its request body uses these values:
|
|
|
|
```text
|
|
{{components.postTitle.value}}
|
|
{{components.postBody.value}}
|
|
{{variables.defaultUserId}}
|
|
```
|
|
|
|
Component values come from the page that invoked the action. `defaultUserId` is a global number variable with default value `1`.
|
|
|
|
Use **Test Action** only to understand its limitation: action testing has no interactive Preview component state. Template-driven actions should be exercised from Preview, where the components have runtime values.
|
|
|
|
## 5. Inspect the response bindings
|
|
|
|
In **Actions & Bindings**, expand **Response Bindings**. The POST action has two `onSuccess` bindings:
|
|
|
|
| Source | Target | Result |
|
|
|---|---|---|
|
|
| `actions.action_create_post.response.body.id` | `components.createdPostId.value` | Shows the returned ID in the Status Panel. |
|
|
| `actions.action_create_post.response.body` | `components.createResponse.value` | Shows the complete body in the JSON Viewer. |
|
|
|
|
Bindings move response data into runtime component properties. They do not modify authored defaults or save API responses in project JSON.
|
|
|
|
## 6. Explore pages, page events, and tables
|
|
|
|
1. Return to **Preview**.
|
|
2. Select **Browse sample posts** or use the automatic page navigation.
|
|
3. Wait for the table to populate.
|
|
4. Select any table row.
|
|
|
|
Opening **Browse Posts** for the first time triggers its page `onLoad` event, which runs **Load sample posts**. Its response body is bound to `components.postsTable.rows`.
|
|
|
|
Selecting a row triggers a different kind of binding:
|
|
|
|
```text
|
|
components.postsTable.selectedRow
|
|
→ components.selectedPost.value
|
|
→ onChange
|
|
```
|
|
|
|
The JSON Viewer displays the selected record without making another REST request. Select **Refresh posts** to run the GET action explicitly, then use **Back to create** to exercise button-based page navigation.
|
|
|
|
## 7. Change a variable
|
|
|
|
Open **Actions & Bindings**, expand **Variables**, and inspect `defaultUserId`.
|
|
|
|
This global number is used by both actions:
|
|
|
|
- the POST body assigns the simulated post to that user; and
|
|
- the GET query filters the table by that user.
|
|
|
|
Change its default from `1` to `2`, return to Preview, and reload or re-enter the Browse page. The table should now show posts for user 2. This illustrates how one declared value can drive several request fields.
|
|
|
|
## 8. Add a component
|
|
|
|
Return to **Visual Editor** and add one component of your choice. For example:
|
|
|
|
1. Select the **Create a Post** page.
|
|
2. Add a **Checkbox**.
|
|
3. Name it `reviewedTutorial`.
|
|
4. Set its label to `I reviewed this tutorial`.
|
|
5. Move it beneath the navigation button.
|
|
|
|
Preview the application and interact with it. The checkbox value exists only during that loaded Preview session unless you deliberately use it in a request template.
|
|
|
|
## 9. See validation protect the project
|
|
|
|
1. Open **JSON Editor**.
|
|
2. Find the Create post Button's `actionId` value: `action_create_post`.
|
|
3. Temporarily change it to `missing_action`.
|
|
4. Select **Apply**.
|
|
|
|
Conductor should report a semantic reference error and preserve the last valid project. Correct the value or select **Revert**. This is the same validation gate used by Apply, Save, Update, Load, and Publish.
|
|
|
|
## 10. Save and reload
|
|
|
|
1. Return to **Visual Editor**.
|
|
2. Select **Save**.
|
|
3. If prompted, keep the name `Conductor Tutorial — Post Workshop` or choose a unique tutorial name.
|
|
4. Make another small edit and select **Update**.
|
|
5. Select **New**, confirm the discard prompt only if no unsaved work remains, then select **Load** and reopen the tutorial project.
|
|
|
|
The authored pages, components, actions, bindings, and variable should return. Preview-only values and API responses should not.
|
|
|
|
## 11. Review history
|
|
|
|
Open **Execution History**. The GET and POST attempts should appear with method, sanitized URL, outcome, duration, status, size, and a bounded response preview.
|
|
|
|
History is for troubleshooting. It does not store request or response headers, cookies, credentials, or sensitive query values. Use **Clear history** only when you intentionally want to remove all retained execution records.
|
|
|
|
## 12. Publish the application
|
|
|
|
Because both tutorial actions use anonymous authentication, the project can be published publicly.
|
|
|
|
1. Confirm the project is saved and valid.
|
|
2. Open **Publishing**.
|
|
3. Select the tutorial project.
|
|
4. Enter a display name and a unique slug such as `post-workshop`.
|
|
5. Choose **Public** or **Restricted to users**.
|
|
6. Select **Publish**, then **Open app**.
|
|
7. Test both pages and refresh the `/apps/<slug>/browse-posts` deep link directly.
|
|
|
|
Saving the source project does not update the live snapshot. Make a visible source edit, save it, and use **Republish** to learn that lifecycle. **Unpublish** removes public access without deleting the source project.
|
|
|
|
## 13. Where credentials fit
|
|
|
|
This tutorial deliberately uses anonymous actions. For a real protected API:
|
|
|
|
1. An administrator creates an encrypted credential under **Actions & Bindings → Secrets**.
|
|
2. The action selects its authentication type and the compatible opaque secret reference.
|
|
3. Conductor injects the credential server-side; it never places the value in project JSON or the published browser application.
|
|
|
|
Public applications cannot contain credential-backed actions. Choose restricted visibility for such an application. Never paste credentials into URLs, headers, templates, tutorial data, or JSON.
|
|
|
|
## Next steps
|
|
|
|
- Use the [User Guide](USER_GUIDE.md) as the feature reference.
|
|
- Use the [Project Schema](SCHEMA.md) when editing JSON directly.
|
|
- Use the [Administrator Guide](ADMIN_GUIDE.md) for accounts, credentials, publishing, and security boundaries.
|
|
- Use [Troubleshooting](TROUBLESHOOTING.md) if a request or published route fails.
|