Stacks

A stack is a set of cards you look at one at a time, in the tradition of HyperCard. Cards sit on backgrounds, and cards and backgrounds hold buttons, fields (boxes of text), pictures, videos and other parts such as lists, sliders and drawings. A stack can be an address book, a set of flash cards, a recipe file or a small game, and the people you share it with can use it with you at the same time.

This article is for anyone who wants information laid out as cards: how to make a stack, how to use one, how to lay out its cards and give its buttons something to do, and how to use one together.

Cards, backgrounds and parts

Every card sits on one background. What is on the background appears on every card that uses it; what is on a card appears on that card alone. Put a Name field and a Phone field on a contact background, and each card shows its own name and its own phone number in the same place.

That is how a field on a background behaves: it holds its own text on each card. A background field marked Same text on every card holds one text for all of them instead, which suits a heading or a note.

Finding your stacks

Stacks have their own app, Stacks, in the dock. The menus reach them too: File ▸ New ▸ Stack, File ▸ Open ▸ Stack…, and the View ▸ Stacks submenu, whose All Stacks opens the list.

The list page, titled Stacks, works like the Builder’s. Type a name in the field marked “Name a new stack, like Recipes” and press New stack. On each row, a star makes it a favourite, and its ⋯ menu holds Rename…, Details…, Databases…, APIs…, Share…, Move to… (a folder), Export… and Delete…, with Install App where it is offered. Folders are the same ones your creations use. A stack is a kind of creation, so what The Builder says about exporting, moving and deleting one holds for a stack too.

Browse: using a stack

A stack opens in Browse, ready to use.

• ◀ and ▶ move to the previous and next card. So do the left and right arrow keys, and Home and End go to the first and last. The counter between them shows where you are, such as “2 / 12”.
• Find, or Ctrl+F (⌘F on a Mac), opens a box: type some text and press Enter to go to the next card that contains it. “Not found.” means no card does.
• Card ▾ holds New Card, which adds a card after this one, and Delete Card, which deletes a card you added. A card that is part of the stack’s design is deleted in Author mode instead, and the stack says so.
• Type in a field and what you type is saved by itself, for everyone who uses the stack. A field marked locked takes no typing.
• The same goes for a choice in a list, a slider, a toggle or a drawing: each card keeps its own, and everyone sees it.

Author: laying out cards

Browse and Author sit at the top right of the stack. Author mode appears only for the stack’s owner, on the owner’s own computer; nobody opening it from elsewhere sees it. In Author mode a second bar holds the tools.

• Select, Button, Field and Image…: choose a tool and click on the card to place a part there.
• More ▾ adds the other kinds of part, described below, in the middle of the card.
• With Select, drag a part to move it and drag its handles to resize it. The arrow keys nudge it by a pixel, or ten with Shift. Delete removes it, and Ctrl+D (⌘D) duplicates it.
• Edit Background puts new parts on the background rather than the card, so every card on that background shares them. Press it again to go back to the card.
• New Card, Duplicate Card, Delete Card and New Background change the stack’s cards.
• Stack…, Background… and Card… open that object’s properties in the panel on the right: its name, its colour, the stack’s size, and its script.

Selecting a part shows its properties in the same panel: its name, the label of a button or the text of a field, its style, alignment and text size, its position and size, its text colour and fill, whether it is visible and whether it is locked — and its Script.

Changes save by themselves, and every save is kept as a version. Undo undoes the last saved change.

Pictures and videos

In Author mode, paste a picture with Ctrl+V (⌘V on a Mac) and it lands on the card at its own size, scaled down if it is wider or taller than about three-fifths of the stack. You can also drag pictures and video files from your computer onto the card, or use Image…. Pictures and videos are kept as files of the stack, so they travel with it when you share or export it.

More ▾ ▸ Video… asks where the video comes from:

• A file…: an MP4 or WebM file of up to 5 MB, kept in the stack.
• A YouTube or Vimeo link…: paste the video’s link, and the card shows that site’s player. Use a link for anything longer than a short clip. Links to other video sites are refused: “Only YouTube and Vimeo links can be shown.”

A selected video’s properties include Show controls, Play automatically (muted) and Loop, and its Link or file can be changed at any time.

More kinds of part

More ▾ holds:

• Shape and Line: a rectangle, oval, line or arrow, with its own border, border width, fill and, for a rectangle, rounded corners. Shapes are for looks; nobody types in them.
• Dropdown and List: a choice among texts you write under Choices (one per line).
• Slider: a number between a Min and a Max, in steps.
• Toggle: an on/off switch with a label.
• Progress bar: shows a number between a minimum and a maximum. People don’t change it themselves; a script does.
• Drawing: a pad to draw on with the mouse or a finger, with six pen colours and Clear.
• Video…, described above.

A list’s choice, a slider’s number, a toggle and a drawing are kept per card, like a field’s text. Put a slider on a background and every card gets its own setting.

Scripts

A script is JavaScript, and it is what makes a button do something. A script declares handlers named after the messages they answer. On a button, function mouseUp() { go('next'); } goes to the next card when the button is clicked.

A message travels from the button or field to its card, then to the background, then to the stack, until a script handles it. A handler that wants the message to carry on calls pass(). A script on the background therefore answers for every card on it, and one on the stack answers for the whole stack.

The commands a script uses most:

• go('next'), go('prev'), go('first'), go('last'), or go() with a card’s name or number;
• find(text), to go to the next card holding text;
• field('Name').text, to read or set a field’s text, and button('Name').hilite, whether a button is checked;
• part('Name').value, to read or set the value of a list, slider, toggle or progress bar;
• answer('Hello') to show a message, and ask('Your name?') to ask for a reply;
• newCard(), deleteCard() and beep();
• send(data) to send something to everyone else in the stack, which their scripts receive in a roomMessage(data, from) handler;
• api('Orders').get('/orders') to call an API you allowed with APIs…, and database('Name') to reach a database you connected with Databases….

When someone changes a list, slider, toggle or drawing, it sends valueChanged(value). A slider named Volume could fill a progress bar with function valueChanged(v) { part('Level').value = v; }.

A broken script never stops the stack. The line under the card reads “Script error in” and names the button, field, card, background or stack whose script failed, and everything else keeps working.

Cards from a table

A background can take its cards from records instead of from cards you make one by one, with no script at all. In Author mode, select the background — with Edit Background or Background… — and under Cards from choose one of:

• A table in this stack;
• A database, one you connected to the stack with Databases…;
• An API, one you allowed with APIs….

Then pick the rest from the lists that appear:

• A table in this stack: choose a Table, or New table… to make one.
• A database: choose the Database, then its Table. The list shows the databases this stack is connected to, each marked “can view” or “can change”.
• An API: choose the API, then the Path that lists the records, such as /people. Other… takes a path you type.

Then select each field, list, slider or toggle on that background and choose its Column, such as name or phone, from the table’s columns. For a table in this stack, New column… adds one.

Connecting a database or API from the stack

You don’t need to leave the stack to connect it. At the end of the Database list is Connect a database…, and at the end of the API list, Allow an API…. Choosing one opens a XataWorks window, “Connect a database to” or “Let … call an API”, that lists yours. Pick one and, for a database, Can view or Can change, then press Connect or Allow. Nothing is connected until you press it, and Cancel connects nothing.

This window belongs to XataWorks, not to the stack: a stack can ask for a connection but can never grant one itself, and it only ever learns about the databases and APIs you connect to it. Connecting a database needs a plan that includes databases, the same as Databases… on the stack’s row.

If a background names a database or API the stack isn’t connected to — say, after you disconnected it — the panel says “This stack isn’t connected to” it, with a Connect… button.

In Browse mode the background then shows one card per record. Typing in a field changes that record, New Card adds a record and Delete Card deletes one, for everyone using the stack. Each person can do only what they are allowed to do with that data: what a connected database allows the stack, and, for an API, what the API allows that person.

Sharing, and using it together

Share… on a stack’s row shares it with people, groups or your organization, each at Can view or Can use. They open it in a browser by signing in to a XataWorks account. It still runs from this computer, so this computer has to be on with XataWorks running.

• Can use lets a person type in fields, change lists, sliders, toggles and drawings, and add cards.
• Can view lets a person browse, and nothing more: fields, lists, sliders, toggles and drawings are locked for them, and there is no New Card or Delete Card.
• Authoring — the layout and the scripts — stays with you, on your own computer.

Everyone in a stack sees who else is there and which card each person is on, in the bar at the top: “Sam · card 5”. What one person types appears for the others within a few seconds.

Asking the agent

The agent can make a stack for you. Describe it in a chat, for example:

• “Make me a flash-card stack for Spanish verbs.”
• “Make a stack of my team’s contact cards from my Contacts database.”

XataWorks asks you before the stack is made, as it does before the agent makes a creation. What each answer to that question means is covered in Approvals and permissions.

Good to know

• A stack is a creation. It is kept, versioned, exported and moved the way a creation is, and it is boxed in the same way: it reaches only the databases and APIs you connect to it, from its row or from the panel in Author mode.
• Files have a size limit. A picture or video kept in a stack can be at most 5 MB, and a whole stack 25 MB. For a longer video, use a YouTube or Vimeo link.
• Web videos need the internet. A YouTube or Vimeo video plays from that site, for whoever is watching.
• Stacks live on your computer. Others use a stack you share while your computer is on with XataWorks running.
• Only you author. Layout and scripts change only in Author mode, on your own computer.