Skip to content

TW changes, consolidated files, and fixed broken links #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

TW changes, consolidated files, and fixed broken links #19

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e973b65
TW changes, consolidated files, and fixed broken links
jcayx May 16, 2023
4ab46c7
renamed files, typographical changes from reviews
jcayx Jun 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 174 additions & 0 deletions docs/howto/getting_started_markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,180 @@ development. For more information on Configuration Panel GUI
development, go to [Alteryx UI
SDK](https://help.alteryx.com/developer-help/ayx-ui-sdk).

## Platform SDK Quickstart Guide

#### Python SDK v2

The steps below illustrate how to use the latest developer tools to
create a custom plugin or tool for use in Alteryx. For more information
about new SDKs and their usage within Alteryx, please visit [Platform
SDK](../references/platform-sdk.md).

### Requirements and Prerequisites

Before you get started, make sure that these items are installed on your
machine:

- Microsoft Windows 7 or Later (64-bit)
- Alteryx Designer Version 2021.2\*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the asterisk?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here it indicates the note below the list with the asterisk is related to this line. Bit confusing imo but this information matches our other documentation

- Python Version 3.8.5
- [pip](https://pypi.org/) (automatically installed with Python 3.8.5)
- [node](https://nodejs.org/en/download/) [14](https://nodejs.org/en/blog/release/v14.17.3/)
- [Git](https://git-scm.com/downloads)

\*Alteryx Designer version 2021.4 or greater is required to use the Alteryx Python
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the asterisk?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see above comment

SDK v2.0.0.

### CLI

The AYX Plugin CLI provides you with a set of utilities to manage your
plugin and is a great starting point for building a tool. AYX Python SDK
installation is also covered in this section.

Follow these steps to get started with the CLI:

1. Run this command to install the AYX Plugin CLI:\
\
`pip install ayx-plugin-cli`\
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are already covered in Install at the top of the doc.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed this section and included link to the earlier part of the doc


2. To verify that you installed the CLI properly, run this command:\
\
`ayx_plugin_cli version`\
\
If the installation was successful the above command returns the
version number. If the CLI was not installed properly, the
`ayx_plugin_cli` command is not recognized in the terminal, and your
terminal reflects that.\

3. Run this command to install the AYX Python SDK:\
\
`pip install ayx-python-sdk`\
\
*(Optional) Create a new directory to house all of your workspaces
and plugins, and continue the steps in this guide from the new
directory. This helps keep your folder structure clean.*\

4. Once the installation is successful, run this command to create a
workspace:\
\
`ayx_plugin_cli sdk-workspace-init`\
\
The command asks you to provide information about your workspace
through a series of prompts.\

5. Once you have stepped through the above command, run this command to
create a custom tool or plugin:\
\
`ayx_plugin_cli create-ayx-plugin`\
\
The command asks you to provide information about your tool or
plugin through a series of prompts. Note that this operation can
take a minute to complete.

Once you have stepped through the above command, you can go to the
location of your workspace and view the files that were created for the
new plugin.

For more information about the CLI, please visit the [reference
documents](../references/ayx-plugin-cli.md).

### UI SDK

The UI SDK consists of 2 pieces.

- The 1st piece is a React-based [component
library](https://alteryx.github.io/alteryx-ui/)
that enables you to build the interface for your tool or plugin.
- The 2nd piece is a [communication
bridge](https://alteryx.github.io/react-comms/)
that lets you interact with Alteryx Designer and persists the values
that you want to save between runs of a workflow, clicking on and
off a tool. These are also the values that are available to the
engine (back end) of your tool.

For the real-time Dev Harness that assists in tool UI development, refer to [Dev Harness.](https://github.com/alteryx/dev-harness)

Follow these steps to get started with the UI SDK:

1. To start on the user interface of your project, navigate to the
folder that was created for your workspace in the last step of the
CLI section above. In this workspace folder, there is a UI directory
for the workspace. There is a folder inside of this directory with
the same name as the plugin you created.
2. Navigate to [\[workspace directory\]\\ui\\\[plugin
name\]\\src\\src]{.path} for the tool you are working on.
3. Open the index.tsx file. This is the primary
[React](https://reactjs.org/)
file for the tool UI.
4. Make a change to the file. For example, edit the text of a tag, or
add a [new
component](https://alteryx.github.io/alteryx-ui/)
or HTML element to the page.
5. Save the file.
6. For a quick preview of your tool in a browser, run this command:\
\
`npm run start`
7. To view your tool in Alteryx Designer, run this command from the
root workspace directory. This command builds and installs your
plugin into Designer.\
\
`ayx_plugin_cli designer-install`

Open Alteryx Designer, search for your tool, place it on the canvas, and
view the changes.

For more information about the UI SDK, please visit the [reference
documents](https://alteryx.github.io/alteryx-ui/).


### Python SDK


The Python SDK defines the way that you should create the engine/back
end/runtime of your tool. The back end also receives the configuration
values that were created by the front end of the tool in the UI SDK
section.

Follow these steps to get started with the Python SDK:

1. To start on the engine or runtime of your project, navigate to the
folder that was created for your workspace in the last step of the
CLI section above. In this workspace folder, there is a back-end
directory for the workspace.
2. Navigate to [\[workspace directory\]\\backend\\ayx_plugins\\\[plugin
name\].py]{.path} for the tool you are editing.
3. Make changes to the file.
4. Save the file.
5. Run this command from the root workspace directory. This builds and
installs your plugin into Alteryx Designer.\
\
`ayx_plugin_cli designer-install`

Open Alteryx Designer, search for your tool, place it on the canvas, and
view the changes.

For more information about the Python SDK, please go to the [reference
documents](../references/platform-sdk.md) or access the full [Python
SDK documentation](https://alteryx.github.io/ayx-python-sdk/index.html).
You can also access this documentation locally via this command:

`ayx_python_sdk docs`


### Troubleshooting

- If you get a workflow error that says 'Can\'t find plugin
\"SdkEnginePlugin.dll\"\', or \"This tool is only supported in the
AMP Engine. Please enable AMP to use this tool.\", [enable the AMP
engine](https://help.alteryx.com/20223/designer/alteryx-amp-engine)
for the workflow.
- If your tool panel does not render or shows a blank screen, [enable
Chrome Developer
Tools](https://help.alteryx.com/developer-help/html-developer-tools).
Now, when you select your tool a Chrome debugger is presented and
you can see any errors for the tool interface.


------------------------------------------------------------------------

### Glossary
Expand Down
172 changes: 0 additions & 172 deletions docs/howto/platform-sdk-quickstart-guide.md
View file
Open in desktop

This file was deleted.

10 changes: 5 additions & 5 deletions docs/references/ayx-plugin-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,7 @@ these commands:

This creates an isolated development environment that minimizes the risk
of creating a package that Alteryx Designer and other users won\'t be
able to use. It does this by keeping the dependencies required by
different projects separate.
able to use. It keeps the dependencies that different projects require separate.

### Installation

Expand Down Expand Up @@ -100,7 +99,7 @@ the current directory, and throw an exception otherwise.
### Parameters

Note: If a parameter is not passed in as part of the CLI call, the CLI
will wait for standard input for the ignored parameters, even if they're
waits for standard input for the ignored parameters, even if they're
optional.

#### \--package-name
Expand Down Expand Up @@ -175,12 +174,13 @@ these, follow these steps:
### Parameters

Note: If a parameter is not passed in as part of the CLI call, the CLI
will wait for standard input for the ignored parameters, even if they're
waits for standard input for the ignored parameters, even if they're
optional.

#### \--tool-name

This parameter becomes the name of the tool. Spaces are allowed but are cleaned into underscores and Pascal case. For example, for a Python
This parameter becomes the name of the tool. Spaces are allowed but are cleaned into underscores and Pascal
case. For example, for a Python
plugin named "A Test Tool", the filename is `a_test_tool.py`, and the
`class/ui/config` name is `ATestTool`.

Expand Down
2 changes: 1 addition & 1 deletion docs/references/ayx-python-sdk-v2-example-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
### Example Tools

These are example tools created using version 2 the [AYX Python
SDK](./ayx-python-sdk-v2.md). When the tools are installed, they display in the SDK
SDK](./platform-sdk.md). When the tools are installed, they display in the SDK
Examples tool category in Alteryx Designer.


Expand Down
Loading