From 605ebb151922a75b48ce91ce7bf6200d556ca450 Mon Sep 17 00:00:00 2001 From: Graham Trott Date: Tue, 23 Jun 2020 12:26:00 +0100 Subject: [PATCH] Doc update and bug fixes --- iwsy/demo.html | 17 +++++++++++ iwsy/iwsy.js | 8 +---- iwsy/resources/ecs/content.txt | 1 - iwsy/resources/ecs/help.txt | 8 ++--- iwsy/resources/ecs/steps.txt | 3 +- iwsy/resources/help/about.md | 6 ++-- iwsy/resources/help/action-chain.md | 7 +++++ iwsy/resources/help/action-fade.md | 2 +- iwsy/resources/help/action-pause.md | 2 ++ iwsy/resources/help/contents.md | 28 ++++++++++++----- iwsy/resources/help/embed.md | 36 ++++++++++++++++++++++ iwsy/resources/help/iwsy.md | 28 +++++++++-------- iwsy/resources/help/quickstart.md | 24 ++++++++------- iwsy/resources/help/quickstart2.md | 26 +++++++++------- iwsy/resources/help/quickstart3.md | 47 ++++++++++++++++++++++------- iwsy/resources/help/technical.md | 23 ++++++++++++++ 16 files changed, 194 insertions(+), 72 deletions(-) create mode 100644 iwsy/demo.html create mode 100644 iwsy/resources/help/action-chain.md create mode 100644 iwsy/resources/help/embed.md create mode 100644 iwsy/resources/help/technical.md diff --git a/iwsy/demo.html b/iwsy/demo.html new file mode 100644 index 0000000..73787c1 --- /dev/null +++ b/iwsy/demo.html @@ -0,0 +1,17 @@ + + + + + + + + + + +
+ +
+ + + + diff --git a/iwsy/iwsy.js b/iwsy/iwsy.js index a779bd4..3c14873 100644 --- a/iwsy/iwsy.js +++ b/iwsy/iwsy.js @@ -595,11 +595,6 @@ const IWSY = (playerElement, scriptObject) => { } }; - // Embed another script - const embed = step => { - step.next(); - }; - // Restore the cursor const restoreCursor = () => { player.style.cursor = `pointer`; @@ -821,8 +816,7 @@ const IWSY = (playerElement, scriptObject) => { crossfade, transition, goto, - load, - embed + load }; // Process a single step diff --git a/iwsy/resources/ecs/content.txt b/iwsy/resources/ecs/content.txt index 8a028bc..de3a5d5 100644 --- a/iwsy/resources/ecs/content.txt +++ b/iwsy/resources/ecs/content.txt @@ -69,7 +69,6 @@ Restart: set attribute `src` of AddItem to `resources/icon/plus.png` on click AddItem begin -! put prompt `Name of new content item:` with `new content` into ItemName set Item to object set property `name` of Item to `New content` set property `content` of Item to empty diff --git a/iwsy/resources/ecs/help.txt b/iwsy/resources/ecs/help.txt index 4033b21..e2ca746 100644 --- a/iwsy/resources/ecs/help.txt +++ b/iwsy/resources/ecs/help.txt @@ -85,7 +85,7 @@ GetPage: begin attach Player to `iwsy-embed` put attribute `data-url` of Player into Data - rest get Embed from Data + rest get Embed from Data cat `?v=` cat now put the position of the last `/` in Data into N add 1 to N put left N of Data into Data @@ -101,7 +101,7 @@ GetPage: ! Decorate is called for every occurrence of ~...~ in the topic data Decorate: put the payload of DecoratorCallback into Payload - if Payload is `iwsy` put `` into Payload else if Payload is `clear` put `
` into Payload else @@ -127,7 +127,7 @@ ProcessImage: put the position of `:` in Data into N if N is -1 begin - put `` into Payload + put `` into Payload add 1 to ImageCount return end @@ -161,7 +161,7 @@ ProcessImage: add 1 to N end put `` into Payload + cat `?v=` cat now cat `" style="` cat Style cat `" />` into Payload add 1 to ImageCount return diff --git a/iwsy/resources/ecs/steps.txt b/iwsy/resources/ecs/steps.txt index 0becaec..e62c505 100644 --- a/iwsy/resources/ecs/steps.txt +++ b/iwsy/resources/ecs/steps.txt @@ -360,9 +360,8 @@ ASA2: take 1 from N end gosub to CreateNewStep - set element N of Steps to CurrentStep + set element SelectedStep of Steps to CurrentStep ASA3: - put -1 into SelectedStep set property `steps` of Presentation to Steps go to Restart diff --git a/iwsy/resources/help/about.md b/iwsy/resources/help/about.md index fe24dfb..f267aad 100644 --- a/iwsy/resources/help/about.md +++ b/iwsy/resources/help/about.md @@ -6,12 +6,12 @@ ## Contact us - +All enquiries should be sent to [info@iwannashowyou.com](mailto:info@iwannashowyou.com). ## Technical stuff -The ~iwsy~ user interface is coded entirely in [EasyCoder](https://easycoder.github.io) scripts, which download, compile and run as they are needed. Everything is done in the browser; there is no build process for the web app. A small server-side REST module handles user registration and login and manages files created by users and stored on the server. +The ~iwsy~ user interface is coded entirely in [EasyCoder](https://easycoder.github.io) scripts, which download, compile and run as they are needed. Everything is done in the browser; there is no build process for the web app. A small server-side REST module handles user registration and login and manages files created by users that are stored on the server. -There are a little over 3000 lines of code in total. The largest code module (that runs the **Steps** panel opposite) is just over 1000 lines long and typically takes under 50ms to compile. Modules are loaded when they are first needed, so the load time of the web app is around 1.5 seconds (Pingdom Tools). The web app uses about 15MB of heap space while running. +There are a little over 3000 lines of code in total. The largest code module (that runs the **Steps** panel opposite) is just over 1000 lines long and typically takes under 50ms to compile. Modules are loaded when they are first needed and the load time of the web app is around 1.5 seconds (Pingdom Tools). The web app uses about 15MB of heap space while running. We are keen to collaborate with anyone who may have ideas for improving the website and the range of features it provides. Enquiries should be made in the first instance to the email address given above. diff --git a/iwsy/resources/help/action-chain.md b/iwsy/resources/help/action-chain.md new file mode 100644 index 0000000..b381690 --- /dev/null +++ b/iwsy/resources/help/action-chain.md @@ -0,0 +1,7 @@ +~page:contents:Contents~ + +# The `chain` action + +Large, dynamic presentations or slideshows may have dozens or even hundreds of steps, making then increasingly difficult to manage or even to visualize. However, presentations are linear entities that usually comprise a number of independent sections, one following another. If you are working on the introduction part of your show, the rest of it is of little immediate interest - it may as well be another presentation completely. + +To take advantage of this structual feature of the average presentation, ~iwsy~ provides the ~m:chain~ action, which terminates the current show, loads a new one and starts it running. As long as you provide a suitable "bridge" the effect is seamless. Each of the sections can be a full presentation in its own right and can be developed independently of all the others. diff --git a/iwsy/resources/help/action-fade.md b/iwsy/resources/help/action-fade.md index a9eb7c1..f4087f5 100644 --- a/iwsy/resources/help/action-fade.md +++ b/iwsy/resources/help/action-fade.md @@ -18,4 +18,4 @@ When this action runs the blocks referenced are all faded at the same time. You Fades and other animated effects run at 25 frames/sec, as a compromise between visual smoothness and processing requirements. -Next: ~page:action-crossfade:Crossfade block content~ +Next: ~page:action-crossfade:Crossfade~ diff --git a/iwsy/resources/help/action-pause.md b/iwsy/resources/help/action-pause.md index afbc8e7..0383cae 100644 --- a/iwsy/resources/help/action-pause.md +++ b/iwsy/resources/help/action-pause.md @@ -9,3 +9,5 @@ This action pauses the presentation for a given nmber of seconds. The **Action**, **Name** and **Label** properties are present for all actions. The **Duration** property is the time in seconds the pause should take. + +Next: ~page:action-chain:Chain~ diff --git a/iwsy/resources/help/contents.md b/iwsy/resources/help/contents.md index a6e9ae5..22b3987 100644 --- a/iwsy/resources/help/contents.md +++ b/iwsy/resources/help/contents.md @@ -2,7 +2,11 @@ # ~iwsy~ Help - Contents -~page:quickstart:Quick-start tutorial~ **Beginners start here!** +~page:quickstart:Quickstart tutorial~ **Beginners start here!** + +~page:quickstart2:Quickstart tutorial, part 2~ + +~page:quickstart3:Quickstart tutorial, part 3~ ~page:users:User registration and login~ @@ -14,16 +18,24 @@ ## Actions -~page:action-init:The **init** action~ +~page:action-init:The "init" action~ + +~page:action-set-content:The "set content" action~ + +~page:action-show-hide:The "show" and "hide" actions~ + +~page:action-fade:The "fade up" and "fade down" actions~ + +~page:action-crossfade:The "crossfade" action~ -~page:action-set-content:The **set content** action~ +~page:action-transition:The "transition" action~ -~page:action-show-hide:The **show** and **hide** actions~ +~page:action-pause:The "pause" action~ -~page:action-fade:The **fade up** and **fade down** actions~ +~page:action-chain:The "chain" action~ -~page:action-crossfade:The **crossfade** action~ +## Technical -~page:action-transition:The **transition** action~ +~page:embed:How to embed a presentation~ -~page:action-pause:The **pause** action~ +~page:technical:Other technical stuff, statistics etc.~ diff --git a/iwsy/resources/help/embed.md b/iwsy/resources/help/embed.md new file mode 100644 index 0000000..967efa2 --- /dev/null +++ b/iwsy/resources/help/embed.md @@ -0,0 +1,36 @@ +~page:contents:Contents~ + +# How to embed a presentation + +To embed a presentation in your own web page you just need the ~iwsy~ runtime engine and a presentation script. The best place to start is with a stand-alone web page, which is coded like this: +
+``` + + + + + + + + + + +
+ +
+ + + + + +``` +
+All of the resources in this demo are loaded on demand from the CDN attached to the GitHub repository for ~iwsy~, which is part of [EasyCoder](https://easycoder.github.io). + +The ~m:head~ of the document requests 2 scripts. One is the ~iwsy~ runtime engine; the other is a launcher for the presentation, which waits for the page to load then starts things up. + +The ~m:body~ contains a ~m:<div>~ with an ID that is specific to ~iwsy~. Inside this is a graphic that holds instructions on how to run the presentation. Then finally there's a hidden ~<pre>~ element that holds the URL of the presentation script. + +## Doing your own embedding + +When you want to embed a presentation, some of the same things are needed. The ~iwsy~ engine is always required but the launcher function will be probably be provided by your own page code. You will need to study the code in ~m:iwsystart.js~ to see how to do this, but it should be no more than a single page of vanilla JavaScript. The container is the ~m:<div>~ on your page in which you want the show to run. The script can be provided in any way you like; it's just a text file that is passed to ~iwsy~ on startup. diff --git a/iwsy/resources/help/iwsy.md b/iwsy/resources/help/iwsy.md index a437076..8485d5c 100644 --- a/iwsy/resources/help/iwsy.md +++ b/iwsy/resources/help/iwsy.md @@ -1,15 +1,27 @@ ~page:contents:Contents~ +**Beginners** - See our ~page:quickstart:quickstart tutorial~ + # ~iwsy~ - I Wanna Show You -I Wanna Show You (~iwsy~, pronounced "You-zee" as an approximation to the initials) is an online presentation package built to deliver slideshows that either run under manual control or unattended. Instead of being a PC application that's tied to the desktop, ~iwsy~ is entirely browser-based. ~iwsy~ presentations can run here in this web app, they can be embedded in other web pages or they can run as independent web pages. +I Wanna Show You (~iwsy~, pronounced "You-zee" as an approximation to the initials) is a web app you can use to create slideshows that run under either manual control or unattended. Instead of being a PC application that's tied to the desktop, ~iwsy~ is entirely browser-based. ~iwsy~ presentations can run here in this web app, they can be embedded in other web pages or they can run as independent web pages. + +## An example + +Here is a simple show that forms the basis of our ~page:quickstart:quickstart tutorial~: + +~embed:/resources/users/2020/160/1/scripts/demo.json~ ## Quickstart tutorial -These help pages contain everything there is to know about ~iwsy~, but there's a lot to read. Most people just want to get started quickly, so we have a built-in ~page:quickstart:quick-start tutorial~ where you can create a simple presentation - a few slides with text and pictures - in just a few minutes. Once you've completed this first step you'll have a pretty good idea of what ~iwsy~ is all about, and the rest of the help pages won't be nearly as intimidating. +These help pages contain everything there is to know about ~iwsy~, but there's a lot to read. Most people just want to get started quickly so we built a ~page:quickstart:quickstart tutorial~ where you can create a simple presentation - some slides with text and pictures - in an hour or so. Once you've completed this first step you'll have a pretty good idea of what ~iwsy~ is all about, and the rest of the help pages won't be nearly as intimidating. ## Feature summary +There are many slideshow/presentation packages, most being quite similar to PowerPoint. The aim here is not to create another identical one but to tackle one or two of the things the others don't do so well. Top of the list is the ability to embed a show into another web page in a seamless manner. The development of ~iwsy~ is driven by the desire to meet this need rather than to excel at formal presentations. + +We are also working on a range of features for making the pages themselves dynamic. This covers a number of areas such as transitions, "Ken Burns" effects and the use of audio. + The basic features of ~iwsy~ are: - A step editor, where you create a set of steps that together form your presentation @@ -24,16 +36,6 @@ The basic features of ~iwsy~ are: ## Background -~iwsy~ started with a need to embed a slide show in a web page, but rather than just a sequence of pictures I wanted something between that and a video. Videos are time-consuming to make and almost impossible to alter when changes happen to the things being described. Presentation packages such as PowerPoint, on the other hand, lack extensive animation features and are hard to embed in a web page. It seemed to me there was room between the two for a new type of product, and once the idea took hold it was hard to put down. It coincided with the Coronoavirus pandemic, which enforced solitude at home and provided the time for development to take place. - -Much of my previous work in recent years has been in building websites, often of a specialized nature with unusual interactive needs. Not having an exceptional intellect I have difficulty with complexity and this has become something of an obsession over the years. Rather than face the issue directly I devised a programming language suited to those who, like myself, regard excessive complexity as something to be avoided at all costs. The language, called EasyCoder, is itself written in JavaScript and has been applied to a number of web projects. I have yet to find a user interface that it cannot handle. - -EasyCoder takes plain text scripts and compiles them in the browser. This is very quick, typically taking less than 50ms for a 1000-line script. EasyCoder scripts tend to be much shorter than their JavaScript equivalents, though by how much depends on the work being done. More importantly, they are readable by any intelligent person who understands the target domain. The basics of the language can be picked up in a day, which compares with the 3 or 4 months needed to learn React or Angular on top of JavaScript itself. So the long term maintenance prospects of an EasyCoder website such as ~iwsy~ are good as there will always be someone around who can learn it quickly. - -The other main advantage of EasyCoder is that it doesn't have a build process. Scripts are loaded directly into the browser and compiled there. The only build tool needed is a text editor. - -So that's the environment for ~iwsy~. All of the website UI is coded in EasyCoder. The presentation engine itself is just under 1000 lines of vanilla JavaScript and can be used independently of the ~iwsy~ website. This ensures performance is as good as it can get without moving to WebAssembly, though the latter is always an option. - -The project is hosted on GitHub as part of EasyCoder and enquiries are welcome from other programmers who are interested in contributing. The range of transition effects is currently limited so there is considerable scope for extension. An outline plug-in mechanism is also present so it should be possible to enhance the system without major disruption each time. +~iwsy~ started at the beginning of May 2020 with a need to embed a slide show in a web page, but rather than just a sequence of pictures I wanted something between that and a video. Videos are time-consuming to make and almost impossible to alter when changes happen to the things being described. Presentation packages such as PowerPoint, on the other hand, are very flexible when it comes to making changes but lack extensive animation features and are hard to embed in a web page. It seemed to me there was room between the two for a new type of product, and once the idea took hold it was hard to put down. It coincided with the Coronoavirus pandemic, which enforced solitude at home and provided the time for development to take place. ~page:contents:Contents~ diff --git a/iwsy/resources/help/quickstart.md b/iwsy/resources/help/quickstart.md index e47fe7b..b536a0b 100644 --- a/iwsy/resources/help/quickstart.md +++ b/iwsy/resources/help/quickstart.md @@ -14,25 +14,27 @@ Click the **Blocks** button over in the right-hand panel, then click the ~img:/r ~img:resources/users/2020/160/1/images/quickstart/newblock.png:100%~ -Most of these default values are fine as they are; they describe a block that occupies the whole window area. Let's just change the ~m:name~ property to ~m:background~ and the ~m:background~ property to ~m:url('resources/users/2020/160/1/images/SemoigoDawn.jpg')~. When the presentation runs, the effect will be to display a full-size image. This is what the panel should look like now: +Most of these default values are fine as they are; they describe a block that occupies the whole window area. Let's just change the ~m:name~ property to ~m:background~ and the ~m:background~ property to ~m:url('resources/img/quickstart/SemoigoDawn.jpg')~. When the presentation runs, the effect will be to display a full-size image. This is what the panel should look like now: ~img:resources/users/2020/160/1/images/quickstart/first-block.png:100%~ Now let's save our work. There's a **Save** button in the editor panel but this just anchors your changes and updates titles etc. You really need to save the entire project. If you are registered it will go to the ~iwsy~ website, but if not it will be saved to your browser's own storage space. Type the name ~m:quickstart~ in the **Script name** box under the main button bar, then click the ~img:/resources/icon/save.png:icon~ icon in the button bar. It's highly recommended that you click this button regularly so you don't lose your work in the event of something going wrong. -The effect I want to create is for the image to fade up from the white of the screen background. So let's go to to the **Steps** editor and make that happen. +The effect I want to create is for the image to fade up out of the screen background. So let's go to to the **Steps** editor and make that happen. ## Adding some steps -The ~m:init~ step is fine as it is so there's no need to touch it. Click the ~img:/resources/icon/plus.png:icon~ to add a new step, then click the **New step** button. You should see this: +The ~m:init~ step provides information about the container to be used for the show. Its default values are fine so there's no need to make any changes here. So we'll add a second step. Click the ~img:/resources/icon/plus.png:icon~ to add the new step, then click the **New step** button. You should see this: ~img:resources/users/2020/160/1/images/quickstart/newstep.png:100%~ -Click in the Action box and a drop-down list appears: +Click in the Action box and a drop-down list appears of all the available step types: ~img:resources/users/2020/160/1/images/quickstart/actions.png:100%~ -Choose ~m:set~ ~m:content~. Now set the ~m:Name~ property to ~m:set up background~, then click **Save**. It should now look like this: +We'll start with a short pause. When the browser switches to full-screen mode it displays a message for a couple of seconds so we'd like to wait for this to disappear before starting our show. Choose ~m:pause~, then set the ~m:Name~ property to ~m:pause before starting~. We'll have a 2-second pause so set the duration to 2 then click **Save**. + +Now click ~img:/resources/icon/plus.png:icon~ again to add another step. It too starts as **New Step** so click that. As before, click to open the ~m:Action~ list. We want to set up (initialize) our background block,so choose ~m:set~ ~m:content~. Set the ~m:Name~ property to ~m:set up background~, then click **Save**. It should now look like this: ~img:resources/users/2020/160/1/images/quickstart/setup-background.png:100%~ @@ -40,15 +42,15 @@ The ~m:set~ ~m:content~ action lets you set up any number of blocks at the same ~img:resources/users/2020/160/1/images/quickstart/select-background-block.png:100%~ -so select that. The block has no text, but if it did we'd choose it in the **Content** drop-down list. Click the **Save** button for this step, then click the ~img:/resources/icon/save.png:icon~ icon in the button bar. +so select that. The block has no text, just the background defined in the block itself, so leave the **Content** drop-down list empty. Click the **Save** button for this step, then click the ~img:/resources/icon/save.png:icon~ icon in the button bar. ## Fading up -Now we have a block with a background, let's fade it up. Click ~img:/resources/icon/plus.png:icon~ again or click the **Add step after** button. In the new step, open the editor, give it the name ~m:fade up background~ and select the **fade up** action. It should look like this: +Now we have a block with a background, so let's fade it up. Click ~img:/resources/icon/plus.png:icon~ again or click the **Add step after** button. In the new step, open the editor, select the **fade up** action and give it the name ~m:fade up background~. It should look like this: ~img:resources/users/2020/160/1/images/quickstart/fade-up-background.png:100%~ -This action lets you fade up as many blocks as you like simultaneously, so it provides you with the means to add a list. Here we only have a single block so let's add that. Click the ~img:/resources/icon/plus.png:icon~ in the **Blocks** row, then click the empty selector in the new row and choose **background** again. Finally set the duration of the fade to a suitable value; say 2 (seconds). You can use decimal fractions here if you need to. It should now look like this: +This action lets you fade up as many blocks as you like simultaneously, so it provides you with the means to add a list. Here we only have a single block so we'll add that. Click the ~img:/resources/icon/plus.png:icon~ in the **Blocks** row, then click the empty selector in the new row and choose **background** again. Finally set the duration of the fade to a suitable value; say 2 (seconds). You can use decimal fractions here if you need to. It should now look like this: ~img:resources/users/2020/160/1/images/quickstart/fade-up-background2.png:100%~ @@ -56,11 +58,11 @@ If you haven't saved your project recently, do it now. ## Watch it run! -Now it's time to test your work. This will cause the help panel to disappear, but don't worry; you can bring it back by clicking the ~img:/resources/icon/help.png:icon~ button in the toolbar. +Now it's time to test your work, which will cause this help panel to disappear, but don't worry; you can bring it back by clicking the ~img:/resources/icon/help.png:icon~ button in the toolbar. -You have 2 run options. The ~img:/resources/icon/run.png:icon~ button runs the presentation inside ~iwsy~, in the left-hand panel currently occupied by this Help page. The ~img:/resources/icon/fullscreen.png:icon~ button runs it full-screen. Note that the full-screen mode doesn't always start up properly; if you have trouble then put your browser into full-screen mode yourself before clicking ~img:/resources/icon/fullscreen.png:icon~. +You have 2 run options. The ~img:/resources/icon/run.png:icon~ button runs the presentation inside ~iwsy~, in the left-hand panel currently occupied by this Help page. The ~img:/resources/icon/fullscreen.png:icon~ button runs it full-screen. Note: It is possible that the full-screen mode may not always start up properly; if you have trouble then put your browser into full-screen mode yourself before clicking ~img:/resources/icon/fullscreen.png:icon~. -Click the ~img:/resources/icon/run.png:icon~ or ~img:/resources/icon/run.png:icon~ icon in the button bar and enjoy watching your steps run! +Click the ~img:/resources/icon/run.png:icon~ or ~img:/resources/icon/fullscreen.png:icon~ icon in the button bar and enjoy watching your steps run! A couple of things to note. One is that as the presentation runs the steps in the editor take on green backgrounds. With only a single fade this happens too quickly to see, but in a longer presentation you can see where you are at all times. diff --git a/iwsy/resources/help/quickstart2.md b/iwsy/resources/help/quickstart2.md index 54a5297..c919088 100644 --- a/iwsy/resources/help/quickstart2.md +++ b/iwsy/resources/help/quickstart2.md @@ -4,17 +4,15 @@ In ~page:quickstart:Part 1~ we created a presentation that just fades up a background panel. In this part we'll add some text to it and look at some of the actions available. -After the background has appeared, let's hold it on the screen for a couple of seconds. There are 2 actions to do with pausing; one is a simple pause and the other also marks a point at which the viewer of the presentation can intervene. We'll add the first of these actions here; the simple pause. +After the background has appeared, let's hold it on the screen for a couple of seconds. As before, add a new step at the end of your presentation, then go into its editor and name it ~m:pause 2 seconds~. Click the empty selector next to the **Action** label and select the **pause** option. Set the **Duration** to ~m:2~ then save the step (or click ~img:/resources/icon/save.png:icon~ as before). -As before, add a new step at the end of your presentation, then go into its editor and name it ~m:pause 2 seconds~. Click the empty selector next to the **Action** label and select the **pause** option. Apart from the properties common to all fields, this one just has a **Duration**, so type ~m:2~ here then save the step (or click ~img:/resources/icon/save.png:icon~ as before). - -We're going to bring up some text in the center of the screen, zooming it from a point below the center line. This presentation is to be some slides about Italian villages, so let's create our first content item. Click the **Content** button and then the ~img:/resources/icon/plus.png:icon~ icon. Open the editor for the new item; it should look like this: +We're going to bring up some text in the center of the screen, zooming it from a point below the center line. This presentation is to be some slides about villages in Liguria, the region of Italy that borders the northern Mediterranean, so let's create our first content item. Click the **Content** button and then the ~img:/resources/icon/plus.png:icon~ icon. Open the editor for the new item; it should look like this: ~img:resources/users/2020/160/1/images/quickstart/new-content.png:100%~ -Set the name to ~m:Italian villages~ then put the same text into the empty box. As usual, save your work. +Set the name to ~m:Ligurian villages~ then put the same text into the empty box. As usual, save your work. -What you've done is create a content item whose name is the same as its content (but it often won't be). When you refer to the name in the **Steps** editor you get the content, so if you use the same content in several places this saves repeating it each time and ensures all the affected slides get changed at once. +What you've done is create a content item whose name is the same as its content (but it usually won't be). When you refer to the name in the **Steps** editor you get the content, so if you use the same content in several places this saves repeating it each time and ensures all the affected slides get changed at once. The title will end up in the middle of the screen, but to make it more challenging let's get it to zoom up from a point in the bottom third of the screen. For this we need 2 blocks. One holds the text and defines the starting point of the zoom effect. The other holds the final position of the block after the zoom has finished. @@ -36,16 +34,22 @@ Now go to the **Steps** panel. The first thing to do is to initialize the **main ~img:resources/users/2020/160/1/images/quickstart/setup-background.png:100%~ -Click the ~img:resources/icon/plus.png:icon~ in the **Blocks** row to add a new block. Select the **main title** block and then select **Italian villages** from the **Content** drop-down list. Change the name of the step to **set up blocks** and the result should be: +Click the ~img:resources/icon/plus.png:icon~ in the **Blocks** row to add a new block. Select the **main title** block and then select **Ligurian villages** from the **Content** drop-down list. Change the name of the step to **set up blocks** and the result should be: -~img:resources/users/2020/160/1/images/quickstart/setup-blocks.png:100%~ +~img:resources/users/2020/160/1/images/quickstart/setup-blocks-2.png:100%~ -If you prefer, you can add a separate step to initialize each block, but it's usually better to do them all at the same time, in one place. +If you prefer, you can add a separate step to initialize each block, but in this case we'll do them all at the same time, in one place. -The animated text effect is done with a **transition** action. Add a new step to your presentation, call it **zoom up title** and choose the action type **transition**. Set **block** to **main title** and **target** to **center title**: +The animated text effect is done with a **transition** action. Add a new step to your presentation, choose the action type **transition** and call it **zoom up title**. Set **block** to **main title** and **target** to **center title**: ~img:resources/users/2020/160/1/images/quickstart/zoom-title.png:100%~ Now you can run your presentation again. The background will fade up first, then after a couple of seconds the text will zoom up. -In the ~page:quickstart3:final part of this tutorial~ we'll add the first of what might in a real presentation be a large number of similar slides, each one describing a different Italian village. +Add another pause, say 3 seconds, then another action, selecting **fade down**. Call it **fade down title and background**. Add 2 blocks, picking **main title** and **background**. Set the duration to 2 seconds. You should have this: + +~img:resources/users/2020/160/1/images/quickstart/fade-down.png:100%~ + +Finally, add another pause of a second. + +In the ~page:quickstart3:final part of this tutorial~ we'll add the first of what might in a real presentation be a large number of similar slides, each one describing a different Ligurian village. diff --git a/iwsy/resources/help/quickstart3.md b/iwsy/resources/help/quickstart3.md index f797625..e206977 100644 --- a/iwsy/resources/help/quickstart3.md +++ b/iwsy/resources/help/quickstart3.md @@ -2,11 +2,11 @@ # ~iwsy~ Quickstart, part 3 -In ~page:quickstart:Part 1~ and ~page:quickstart2:Part 2~ we created an introduction that fades up a background panel and zooms up a title. In this part we'll add a typical presentation page, one of what would often be many having a similar format. Our theme is Italian villages and here we'll add the first one; Manarola, one of the famous Cinque Terre villages in Liguria. +In ~page:quickstart:Part 1~ and ~page:quickstart2:Part 2~ we created an introduction that fades up a background panel and zooms up a title. In this part we'll add some typical presentation page, one of what would often be many having a similar format. Our theme is Ligurian villages and here we'll add the first one; Manarola, one of the famous Cinque Terre villages. Click the **Content** button opposite, then click ~img:resources/icon/plus.png:icon~ to add a new content item. Set the name to ~m:Manarola~ then paste the following text into the empty box: -> ~m:CINQUE TERRE – MANAROLA~ +> ~m:Cinque Terre - Manarola~ > ~m:Romantic Manarola – a hamlet of Riomaggiore – spills down a ravine to the wild and rugged Cinque Terre coastline. Besides its natural beauty, the village is also famous for its sweet Sciacchetrà wine, celebrated by Gabriele D'Annunzio in one of his amazing poems. Manarola has brightly painted houses, priceless medieval relics and a tiny harbour that features a boat ramp and a swimming hole; to the north, on the way to Corniglia, there's a stunning viewpoint (Punta Bonfiglio) where visitors can enjoy a drink in a bar between the village’s cemetery and the sea. Everywhere is the scent of the lemon trees, thyme, rosemary and Mediterranean maquis; the grapevines – grown on terraces – embrace the village in a tight hug.~ ~img:resources/users/2020/160/1/images/quickstart/manarola-content.png:100%~ @@ -15,23 +15,23 @@ As usual, save your work, then click the **Blocks** button. We'll have a 2-colum ~img:resources/users/2020/160/1/images/quickstart/manarola-text.png:100%~ -~img:resources/users/2020/160/1/images/quickstart/manarola-photo.png:100%~ +~img:resources/users/2020/160/1/images/quickstart/manarola-photo.jpg:100%~ -Now Click the **Steps** button. Click the **set up blocks** step. You need to add the Manarola text and photo blocks so they will be ready when needed. Make the step look like this: +Now Click the **Steps** button. We need a **set content** step; we could add to the one we created at the start but sometimes it makes more sense to do it where it will be used. Add a new step; pick the **set content** action, call it **setup manarola** then add a block; pick **manarola text** and for its content pick **manarola**. Make the step look like this: -~img:resources/users/2020/160/1/images/quickstart/setup-all-blocks.png:100%~ +~img:resources/users/2020/160/1/images/quickstart/setup-manarola.png:100%~ -Add a new step with a 2-second pause, exactly as before, then add 2 more new steps and get them looking like this: +This operation may need time to complete, so let's do it before the block is visible. Add a **pause** of 1 second. -~img:resources/users/2020/160/1/images/quickstart/fade-down-bg.png:100%~ +Now add another new step and get it looking like this: ~img:resources/users/2020/160/1/images/quickstart/fade-up-manarola.png:100%~ -Each of these 2 steps operates on a pair of blocks, and the **continue** in the first step means the following step will run without waiting for this one to finish. In this case it means the 2 fades will run concurrently as a cross-fade. +This step operates on a pair of blocks, which will fade up concurrently. Note that the fade animation will not wait for the content to be ready before starting. Where text has embedded images it takes time to download and render them; this is done at the **set content** step so it's always best to have a pause just after to allow the processing work to complete. Now run your presentation. If everything is correct it should end up like this: -~img:resources/users/2020/160/1/images/quickstart/final-1.png:100%~ +~img:resources/users/2020/160/1/images/quickstart/manarola-1.jpg:100%~ This is OK but obviously needs a little tweaking here and there. Start with the **manarola text** block and adjust it a little, adding a text margin on the left (which also adds the same on the right): @@ -43,12 +43,37 @@ Finally, add the following just in front of the word Romantic, at the start of t ~m:~img:resources/users/2020/160/1/images/quickstart/cinqueterre.jpg:left 50%~~ -This adds an image into the text, using a custom addition to the MarkDown syntax. Everything between the 2 tildes (~) is treated as a special command. It starts with **img:**, which signifies it's an image tag. The URL of the image then follows, after which is another colon then some special tags, in this case one to force the image to "float" to the left and the other being to give it 50% of its container width. Those who are familar with CSS should have little trouble seeing what's happening here. +This adds an image into the text, using a custom addition to the MarkDown syntax. Everything between the 2 tildes (~) is treated as a special command. It starts with **img:**, which signifies it's an image tag. The URL of the image then follows, after which is another colon then some special tags, in this case one to force the image to "float" to the left and the other being to give it 50% of its container width. Those who are familar with CSS should have little trouble seeing what's happening here. The markup causes HTML to be generated to perform the desired task, but you can in fact insert HTML directly into the file if you need some feature we don't offer. (Though this somewhat negates the purpose of using MarkDown in the first place.) Run the presentation again: -~img:resources/users/2020/160/1/images/quickstart/final-2.png:100%~ +~img:resources/users/2020/160/1/images/quickstart/manarola-2.jpg:100%~ Ah, this is a lot better. You may want to adjust the size of the font (in the **manarola text** block) so it fills the screen better, but you'll find you get different results on different browsers. For some reason, Chrome gives smaller text than Firefox does for the same numerical value. +The rest of the items are similar to what we already have. Create another **Content** item called **Apricale**, with this content: + +> ~m:## Provincia di Imperia - Apricale~ +> ~m:~img:resources/users/2020/160/1/images/quickstart/imperia.jpg:left 50%~Apricale is a picturesque small village to the north-east of Dolceacqua in western Liguria and surrounded by forested hills, included on the list of the 'most beautiful villages in Italy'.~ +> ~m:Just one of several attractive hill villages in this region, Apricale is compact and easy to explore. Most of the sights of interest are on or very close to the square in the centre of the village, although of course you will also want to follow the main street along the ridge to enjoy more views and to appreciate the medieval character of Apricale."~ + +Create a third village **Content** item called **Noli**: + +> ~m:## ## Provincia di Savona - Noli~ +> ~m:~img:resources/users/2020/160/1/images/quickstart/savona.jpg:left 50%~The seaside village of Noli lies a few km west of Savona, in the central part of Liguria. Although popular with Italians it's scarcely known to anyone else outside of the area. It's a beautiful quiet and relatively unspoiled gem, with a good beach and right behind it the old town with pedestrian-only streets and a sprinkling of shops and restaurants, all preserving the ancient architecture and topped by a small castle. Although it lies on the main "Via Aurelia" coast road, all the through traffic now goes on the Autostrada, leaving Noli free from noisy vehicles. The coast road is also spectacular and it's well worth forsaking the motorway to explore the coastline between Savona and the busy resorts of Finale Ligure and Loano."~ + +Then create 2 more pairs of **Blocks** similar to the ones for **Manarola**, calling them **apricale text**, **apricale photo**, **noli text** and **noli photo**. The 3 text blocks are in fact identical; the photo blocks only differ by the name of the image file; these 2 are **apricale.jpg** and **noli.jpg**. + +Create a **set content** item for **Apricale** similar to the one for **Manarola**. + +Add a **pause** of a suitable length - say 10 seconds - to hold the **Manarola** page. + +The transitions from one village to the next comprise a fade-down and a fade-up, running concurrently. So for the **Manarola** to **Apricale** transition, add a new **Step**, choosing the **fade down** action. Add both the **manarola text** and **manarola photo** blocks, choose a suitable duration and set the **Continue** flag **true**. This will cause the next action to start without waiting for this one to complete. As both animations run concurrently they give the impression of a crossfade. + +The action in question is a new **fade up** action. Give it the **apricale text** and **apricale photo** blocks, use the same duration as the fade down but leave **Continue** **false**. + +By this time you should be able to handle the transition from **Apricale** to **Noli** without any help. + +As described earlier, after each pair of fade down and fade up, prepare the next item with **set content** and put in a 10-second pause. When you have finished, your presentation should run as a simplified version of the demo that appears on ~page:iwsy:the main Help page~. + And with that we arrive at the end of the Quickstart tutorial. We've really only skimmed the surface but you should at least have an idea of what ~iwsy~ is all about and whether you're likely to want to use it. In the ~page:contents:Contents~ you'll find a lot more detail about all aspects of this web app, as well as contact details and an invitation to join the development team if you wish. diff --git a/iwsy/resources/help/technical.md b/iwsy/resources/help/technical.md new file mode 100644 index 0000000..1f56598 --- /dev/null +++ b/iwsy/resources/help/technical.md @@ -0,0 +1,23 @@ +~page:contents:Contents~ + +# Technical stuff + +The UI of this website is coded in [**_EasyCoder_**](easycoder.github.io), a high-level scripting language that takes plain text scripts and compiles them in the browser as they are required. **_EasyCoder_** scripts tend to be much shorter than their JavaScript equivalents, and more importantly they are readable by any intelligent person who understands the target domain, so the long term maintenance prospects of an **_EasyCoder_** website such as ~iwsy~ are good as there will always be someone around who can learn it quickly. + +The presentation engine itself can be used independently of the ~iwsy~ website. The project is hosted on GitHub as part of **_EasyCoder_** and enquiries are welcome from other programmers who are interested in contributing. The range of transition effects is currently limited so there is considerable scope for extension. An outline plug-in mechanism is present so it should be possible to enhance the system without major disruption each time. + +## Statistics + +The presentation engine is a little over 1000 lines of vanilla JavaScript. + +The UI comprises 3343 lines of EasyCoder scripts. The longest of these, at about 1100 lines, compiles in under 40ms on mid-range (core-i5) hardware. Pingdom Tools report a page load time of just over a second. + +## Structure + +The home page is simply a bootloader for the application scripts themselves. These are plain text files that load on demand and are compiled on the fly by the EasyCoder runtime library. There is no build process and the only tool required is a text editor. + +User management is done with a small PHP REST module that runs on the server and keeps records either in a database or in file storage. Each user is allocated a directory on the server in which are their scripts and uploaded images, the latter which are scaled to a maximum width of 1200 pixels to avoid excessive file sizes. + +~iwsy~ can be used without any login but the features available are restricted. In particular, the file manager is not available so if images are wanted they must be provided as independent URLs. Scripts can still be saved, but go to browser storage. + +~page:contents:Contents~