Forem: Diana Lakatos

Build and Host Anything with platformOS

Diana Lakatos — Tue, 16 Feb 2021 14:07:02 +0000

A getting started guide using an open source ecommerce Marketplace Template to learn from.

What is platformOS?

platformOS (pOS) is a model-based application development platform.

It's like Firebase and Heroku had a baby, but with a lot more flexibility and power. It's infrastructure agnostic, allowing your solutions to be deployed to AWS, GCP and (soon) Azure with all your DevOps taken care of.

Aimed at front-end developers and site builders, it supports any front-end development framework such as React, Vue.js, Angular, Bootstrap, and others. It supports a flexible and limitless API-driven development approach while providing enterprise grade DevOps-in-a-Box to spin up a hosted site and go live in minutes. You can build any solution including community sites, membership based ecommerce club sites, product marketplaces with complex logistics and payment integration, service marketplaces, advanced auctions sites, QA and forums — even stand-alone SaaS applications. (We already have a G2.com #1 ranked Digital Experience Platform built on platformOS)

This article will help you get started with pOS using our Product and Community Marketplace template — a fully functional marketplace built on pOS with features like user onboarding, product/service listings and ads, add-to-cart and checkout process, including online payment via Stripe.

Following the tutorial, you can deploy this code within minutes to have a list of working features and then be able to start customizing the back- and front-end code (without any limits!). You can preview the demo marketplace solution template at getmarketplace.co.

What you'll need

To get started, you'll need to register on the platformOS Partner Portal, an online interface where you can create, manage and configure your sites (called Instances).

To register on the Partner Portal, go to https://partners.platformos.com/accounts/sign_up, complete the form or use your GitHub or Google account. Once registered, you will get an email verification. Click on the Accept verification link to activate your account.

Setup and configuration

Step 1: Install the pos-cli

The pos-cli is a command line interface that helps you deploy configuration files and assets to your pOS site. You will need a recent version of NPM (Node Package Manager) that comes with Node.js installed on your computer to install the pos-cli.

Once you have Node.js installed, start your command-line tool (for example, Terminal on a Mac, or Git Bash on Windows), and enter:

npm install -g @platformos/pos-cli

If your Node.js is installed for all users you might need to use sudo to install npm packages globally:

sudo npm install -g @platformos/pos-cli

Use the following command to test the pos-cli:

pos-cli -v

If the pos-cli has been installed correctly, running this command displays the version of your pos-cli. If the pos-cli hasn't been installed, running this command gives a command not found error.

Step 2: Create Instance

To be able to deploy your site, you have to create an Instance on the Partner Portal. Instances have a URL, and they represent different development environments, like staging or production. We recommend creating a staging environment for going through the steps in this tutorial.

On the Partner Portal, in the menu on the left under Create, select Instance, and fill in the form:

Field	Description	Example
Name	The name of your Instance	mymarketplace
Tags	Enter up to 5 tags (optional). You can use tags to group your Instances, for example by project or client.	marketplace, test
Partner	Select the Partner the Instance will belong to.	MarketplacePartner
Data Center	Select an endpoint (staging or production).	STAGING

Select the Staging/Unbilled Billing Plan that appears, and click on the Create button.

Developing and deploying to a staging Instance is free. Once the Instance is created (in a couple of minutes at most), you'll get an email with a link to your Instance and other useful information.

Step 3: Add Instance to pos-cli

WARNING: Make sure you remember your Partner Portal account email and password --- you will need them to authenticate your environments. If you logged in using Google or Github, go to the Instance details view in Partner Portal where you will find the pos-cli command ready for copy and paste. It shows all the parameters you need, so in this case, you won't need to remember your password.

On your local environment create a new directory and change to it. This is where you will put the codebase for your marketplace.

mkdir marketplace
cd marketplace

Add your Instance to the pos-cli. This will ensure that you can use the pos-cli to download your codebase, and sync or deploy to the Instance.

Use the pos-cli env add command and authenticate with your Partner Portal credentials.

TIP: You can copy this command pre-filled with your email and Instance URL from your Instance page on the Partner Portal.

pos-cli env add [YOUR_ENV_NAME] --email [YOUR_EMAIL] --url [YOUR_INSTANCE_URL]

For example:

pos-cli env add staging --email john.smith@example.com --url https://mymarketplace.staging.oregon.platform-os.com

A message "Environment [your Instance URL] as staging has been added successfully." is displayed.

Step 4: Clone the repository

Create your codebase by cloning our marketplace GitHub repository:

pos-cli init --url <https://github.com/mdyd-dev/product-marketplace-template.git>

Step 5: Build assets

Install the marketplace package and any packages that it depends on then build it using npm commands.

npm install
npm run build

Step 6: Deploy

To be able to display your marketplace on your site, you have to deploy your codebase using the pos-cli deploy command.

pos-cli deploy [YOUR_ENV_NAME]

For example:

pos-cli deploy staging

A progress indicator shows that the deployment is in progress, and once it finishes, a "Deploy succeeded after [time]" is displayed.

Step 7: Set up your marketplace

To access the admin panel of your marketplace:

Register a user with this email address: admin@example.com.
Enter the Admin section from the main menu.
Go to the Marketplace Setup section.

Congratulations, you have successfully created and deployed your first pOS site. Visit your Instance URL to check it out.

Next steps

Visit the pOS documentation to explore all that you can do with pOS. Follow step-by-step Get Started tutorials for beginners, or delve into more advanced topics using the Developer Guide. To meet and learn from fellow developers developing solutions on pOS, join the platformOS Community.

Code and Content for Accessibility on the platformOS Developer Portal

Diana Lakatos — Tue, 03 Nov 2020 13:23:04 +0000

We have recently finished our latest accessibility review on the platformOS Developer Portal. This article describes our approach to accessibility. As our developer portal is open source and all planning, issue tracking, and code and content contributions happen through GitHub, you can get a detailed understanding of our practices and use those insights in your own projects. (And we’d love you to share any of your accessibility learnings, too.)

Code

We address accessibility right from the design phase, where we use Figma’s Able accessibility plugin. We follow the rules for foreground and background color contrast, font size, and graphical objects (like icons, form fields, etc.) to ensure that our site conforms with WCAG AAA. The number of words or characters per line also contributes to readability. That’s why we aim to have 65-75 characters per line.

As another foundation for accessibility, we make sure to only use and correctly use semantic HTML — this helps assistive technologies (like screen readers) convey information to their users by following the semantic structure. In addition to providing and ensuring a consistent structure, semantic HTML ensures that web browsers apply default accessibility features for specific HTML elements. For example, buttons get keyboard accessibility (can be navigated to and clicked using the keyboard).

We regularly test for accessibility with various tools and ensure that the site complies with all accessibility requirements.

Test results of the platformOS Developer Portal:

Lighthouse: Accessibility score 100/100
AChecker (Web Accessibility Checker): WCAG 2.0 (Level AAA) - No known problems

These automated accessibility checkers perform a series of audits on the site and result in a weighted average score and a list of recommendations for improving accessibility. The tests check, for example:

the contrast ratio of the background and foreground colors
structural elements like the title, headings, and if heading elements are in sequentially-descending order, without skipping any level
if image elements have alt attributes
If form elements have associated labels
[aria-*] attributes (Accessible Rich Internet Applications (ARIA) is a set of attributes that define ways to make web content and web applications more accessible)

Find a full list of Lighthouse checks with detailed explanations of each test on web.dev.

We make sure to follow all of these technical recommendations and fix any issues we find.

Content

As semantic HTML is essential for accessibility, we make sure not to style text any other way than through Markdown, which is then translated into HTML. We provide ready-to-use templates for all content types that include all non-changeable content and placeholders with explanations for the parts to add. Placeholders provide information on the recommended format (for example, title) and any requirements or limitations (for example, the maximum number of characters). The templates define the headings structure and levels.

The technical aspects we described so far are only the foundation. To have a truly accessible site, you need to write for accessibility.

We defined the following guidelines in our Documentation Style Guide.

Guidelines for structuring content

Use headers for structuring your content: The Markdown format you write in is translated into semantic HTML to help screen readers navigate through our content. Use headers as described in the style guide and follow the templates we provided to ensure consistency. Never skip a header level for styling reasons.
Improve readability by using concise language, writing short paragraphs, and using lists where applicable.
Use alternative text for images and icons. Keep in mind that screen readers read this text out loud.
If the image serves a function as part of the documentation, describe the image in detail. Users should receive the same information from the alt text that they would receive if they saw the image.
Include the data for charts or graphs in the alt text.
When you use screenshots to show what the user has to do, the alt text shouldn't repeat the information already described in text.
Decorative images don't need alt text — it would only be a distraction.
If you insert an image, pay attention to the contrast ratio, image quality, and its size in kilobytes. The smaller the image, the more accessible it is. Better connections are rarer than bad ones.
Provide information as text as well if you are using videos. Not everyone can use videos efficiently.

Guidelines for accessible language

Be inclusive and global. Use language that reflects your users’ diversity (including, for example, race, gender, ability, location, etc.).

Use definitions for all terminology: Introduce new concepts by starting with a definition, and add them to the Glossary. Explain acronyms at first use.
Use technical language: Use the most specific word you can to talk about technical concepts and processes. For example, don't say "take" when you mean "copy", don't say "put" when you mean "install", etc.
Use gender-neutral pronouns: Avoid using gender-specific, third-person pronouns such as he, she, his, and hers. Use the second person when possible, and "they" when needed.
Use informative link text: To help keyboard navigation, add the information into the link text. For example, instead of writing "learn more" or "click here", write the topic title.
Avoid ableist language: Don't use words that assume an ability the user might not have (for example, "as you can see" implies the user has a capacity for vision). Avoid directional language, for example, "blue button" or "button below the headline".
Don't perpetuate racism, bias, and harm: Replace terms like "blacklist" and "whitelist" with terms like "allowed" or "blocked". Replace "native" with "built-in". Note: If the application you describe includes these terms, you have to use them in the documentation for clarity and consistency.
Avoid metaphors and colloquialisms.

We thought it might be helpful to show some examples of these guidelines in action from our latest accessibility edits. One of the larger tasks was to replace the word “see”, and for this we examined each instance of “see” in our documentation and replaced it with a more fitting, accessible alternative. For example:

Instead of:	We now have:
There is a point in troubleshooting when you just can’t see new approaches anymore.	There is a point in troubleshooting when you just can’t think of new approaches anymore.
You should see that the background color of the page has changed to the color specified in the `app.css` file.	The background color of the page has changed to the color specified in the `app.css` file.
You can also use the `admin_third_party_integrations` query to see the current configuration of any third party integration.	You can also use the `admin_third_party_integrations` query to learn about the current configuration of any third party integration.
After setting up domain authentication, your recipients will no longer see the “via sendgrid.net” message on your emails.	After setting up domain authentication, your emails will not include the “via sendgrid.net” message.
In the Audience ID section, you see a string of letters and numbers.	In the Audience ID section, you find a string of letters and numbers.
Let's use the example to see exactly what is happening at each stage of Model Schema definition life cycle.	Let's use the example to follow exactly what is happening at each stage of Model Schema definition life cycle.
It helps to turn off word-wrap in your editor to see those patterns easier.	It helps to turn off word-wrap in your editor to recognize those patterns easier.

You can find all the changes we made during our latest review in pull requests collected on our ticket in GitHub.

We found that these changes not only made our content more accessible but clearer and more precise.

Resources

We close this article with a collection of resources that we found helpful in making our developer portal more accessible.

18F Accessibility Guide with further links to resources
Accessibility tips for web developers by Addy Osmani
Web.dev Accessibility Scoring
Moving beyond empathy: a11y in documentation by Alexandra White
Don't Say Simply by Jim Fisher

We are continuously working to make our documentation more accessible and usable to the widest possible audience. Please let us know if you have any suggestions for improving accessibility. Thank you!